Maintainability Sp 772 April 29 th 2002 Important

Maintainability Sp. 772 April 29 th 2002

Important Criteria • Easy to understand – New web masters – Old web masters – The user • Easy to update – Bug fixes – New browsers and official specifications – Expansions

Easy to Understand • Documentation – Html comments – Javascript comments – README files • Structure – Use functions – Organized and consistent hierarchy – Reuse files and code (avoid copying)

Code comments • Javascript comments – Explain your functions – Explain complicated or convoluted lines of code • README files – Explain your layout and file structure – Leave instructions on how you planned future updates to work

Structure • Organized hierarchy – Use index. html to control directory access • Do you want users to see your individual files? – Choose a strategy and stick to it. – Put commonly used files at the top of the hierarchy or in a common folder

Reuse • Avoid cutting and pasting of code (javascript) • Put duplicated lines of code into functions • Put commonly used functions into separate files <script src=“myfunctions. js”>

Easy to Update • Use functions – It’s easier to update one function than several blocks of identical code – Helps avoid making the same mistake – Make your functions modular • Isolate browser incompatibilities – Try to put most browser specific code into functions

More update tips • Putting your common javascript functions into separate files – Makes it easier to reuse code between functions • Put styles in separate files – Same reasons as javascript (more on this later)

Archive • Make archives of your site as time goes by – Use progams like winzip (windows), or tar (athena) or stuffit (mac) • Keep one for yourself. – You can reuse your own code on new prjects – You may forget how you once did some cool thing.

Leaving a project • With most web projects there comes a time for you to leave your post as web master – Once you’re done, you’re done: make any changes you want to make. – Consider leaving your contact info so the new web master can follow with questions. – If the site is a mess when you leave it Noone is going to want to wade through it. The New web master will ignore your efforts and add their own style.

Entering a project • When you enter a new project consider how the project was left. – Was there a structure in place? – Is there docmentation you should read? – Are you making an addition to the site or a revision?

Closing words • Documentation is the most often ignored area of programming. • Disorganization is a slippery slope. • Think of all the hours you put into a project and remember that a little extra effort will make your efforts last for much longer.