Maintainability Sp.772 April 29th 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

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 much longer.