Maintainability

1. Maintainability Sp.772 April 29th 2002

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

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

4. 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

5. 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

6. 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”>

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

8. 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)

9. 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.

10. 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.

11. 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?

12. 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.