Re: Source Code Documentation

Subject: Re: Source Code Documentation
From: iluvvscotties -at- earthlink -dot- net
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 14 Apr 2001 08:10:20 -0400

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 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.
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 for more resources and info.

Previous by Author: Re: Source Code documentation?
Next by Author: Re: STC's Response to comments about Annual Conference Program
Previous by Thread: source code documentation
Next by Thread: Re: Source Code Documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads