Progress Programming Tips

PPT-32  Using comments to aid in documentation

Tip:

As developers we know there are many kinds of "Comments" used
throughout source code.

1.  Explaining a particular algorythm
2.  A note to detail a limitation in the features being supported 3. 
The basic purpose description for a block of code

... And so on ...

A technique that can save countless hours after the fact is to
"Specialize" your comments.  These specializations help identify one
type of comment from another when scanning source, especially when
using an automated search tool.

Some examples -

/**[Debug]** Remember to remove this code section! **/

/**[Program Header]**/

/**[Doc]** CalcCost - Procedure to calculate the current cost **/


These examples have no specific merit, they just illustrate that using
some special characters, [] in this case to denote the tag, and some
standards will go a long way towards helping automate using this
knowledge which is often just buried along with the code.

For more advanced efforts I would recommend looking at the existing
standards such as HTML for options and tools as well.  As always there
is a balance between feature and additional work, as well as the cost
in readability if you let it get out of hand.


Wisdom:

Be prepared for change.  Plan for it, find the opportunities in it, or
expect an unpleasant surprise.


Rod Gaither                  | rdg@worldinfo.com
World Information Systems    | (910) 333-2580  Voice
Greensboro, NC               | (910) 333-2584  Fax