Re: Source Code Documentation

[iluvvscotties -at- earthlink -dot- net]

One other point is to red-flag anything that is hard-coded and can thus 
easily cause everything to crash.  This is critically important, since the 
original developer may not be available when that happens.  Red-flagging 
the issue(s) will enable his successors to prevent or at least repair problems.

For example, virtually every language has some form of date functions.  Let 
us say that, in language X, DOW() provides the current day of the week, 
DOM() provides the current day of the month, MO() provides the current 
month, and TODAY() provides the current date -- and that the goal is to 
automatically generate a report assigned variable NewYearRpt on the first 
Monday of each calendar year.

Most good developers would code something along the order of
     If DOW()="MON",DOM()<8, and MO()="JAN", Print NewYearRpt EndIf

However, say that the developer in question instead used the next year's 
exact date -- e.g.,
     If TODAY()="01/07/02" then Print NewYearRpt Endif.

The first example is called generic, since the code will automatically 
generate the report from year to year.  The second method is hard-coded, 
since it uses the exact date (01/07/02), and thus will only generate a 
report on that one date of  one year.

Although generic code is obviously preferable, hard-coding runs faster and 
is much quicker and easier to write.  Programmers are sometimes up against 
harsh deadlines (though no fault of their own -- e.g., the powers-that-be 
may  promise delivery on a certain date, period), and have no choice but to 
take shortcuts.  That's fine, as long as they subsequently take the time to 
make code such as the above generic -- or, at the very least, to red-flag 
it so that problems can be prevented, or at least easily repaired.

The above example is ridiculously simplistic for the purpose of 
example.  However, in the real world, I have seen systems grind to a halt, 
PAYROLLS DELAYED, and programmers called in at 2 AM because something was 
hard-coded and nobody knew about it.

In short, the main purpose of source code documentation is to make the code 
clear (in case it must subsequently be revised, or if the program crashes), 
and prevent and forestall problems.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.