Programming Documentation

This page contains my notes on how to fully document programs in various languages. This is perhaps the most controvertial aspect of programming. So what I have here is simply some examples.

Topics this page:

Site Map  
About this site  

Summary

I am weary of using /* block */ comments in Java and SQL code because comment blocks cannot be nested within each other, which keeps me from quickly/randomly commenting out a large block of code.

However, header blocks at the top of each file is a good place for block comments.

Java Documentation

How to Write Doc Comments for the JavadocTM Tool 1.4 recommends this order:

Example	Comment
/**	- Slash with two asterisks. Javadoc ignores comments following double backslashes.
* Get the stuff for the doohicky.	- The first sentence is the summary. So replace periods in the middle of the sentence with an active verb.
* @author unascribed	- if unknown. (classes and interfaces only, required)
* @version 1.39, 10 May 2003	- (mm/dd/yy) when file is checked out of SCCS. Required for classes and interfaces
*
* @deprecated As of JDK 1.1, replaced by setBounds
* @since
* @param	- One is requuired for each parameter (methods and constructors only)
* @return	- Required for any return value other than void (methods only)
* @exception IOException If an input or output exception occurred	- (@throws is a synonym added in Javadoc 1.2)
* @link http://...#...
* @see document name classname#methodname
* @serial	- identifies fields that are already serialized. (or @serialField or @serialData)
* @serialField	- identifies the order and type of objects in a ObjectStreamField serial stream used by writeObject(), readObject(), writeExternal(), and readExternal() calls.
* @serialData	- identifies objects of type ObjectStreamField, a descriptor class that identifies the characteristics of each serializable field for a given class.
*/	- Notice only one asterisk terminates a comment.

Note: @revision is not a recognized tag.

javadoc also now supports doclets, a pluggable output scheme for technical writers to target XML or other document formats.

Additional Comments	Notes
Known defects and enhancements: A. getxxx doesn't sing.	Name each item using alphabetic letters rather than numbers to avoid confusion with priority numbers.
Unit Tested on Windows XP SP2 with English & French	This gives system testers a basis for debugging.
Using Standards & Conventions http://....com/pgmconv.htm#Java2 version 2.3	provides a basis for reviewer comments
Unit Test Plan at http://....com/pgmconv.htm#Java2 version 1.3
Developing using Eclipse 2.1 IDE

SQL Documentation

/* Phase 2 forecast_series.sql Oracle 8i Interactive SQL query
Lists ... and ... displayed on the ... screen
Values displayed are concantenated with identifiers used to lookup that data.

5-28-02 Wilson Mar - Adapted for Phase 2 schema from Phase 1.
*/

Note the designation of the intended version (Oracale 8i) and whether it's meant to be run in interactive or batch mode.

Note the Change History with date, person name, and description of change.

I try not to duplicating the schema description so I have less maintenance to do when changes occur.

In the FROM and WHERE sections, I like indenting the table names to mimic the hierarchy of the database. Example:

FROM
corporation
companies
employees
schedules
projects
etc.

One piece of "documentation" is the text prompting values users provide at run-time, as in this sample code:

ACCEPT sAge PROMPT 'Enter age of ...'

I think it's useful in data selection code to have comments containing the English translation of internal values specified.

-- and region_lkp.region_nm = 'CENTRAL' -- ®ion_name

When I'm debugging SQL code, sometimes hard code selection values in to save time answering the prompt. In such an approach, I have several selections, each for a specific value. I then comment or uncomment them out as needed.

In the ORDER BY section, I prefer putting commas before each item because most changes occur at the end of the list, and it seems I always forget which item is the last one.