Transcript Maintainability Lecture

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