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.
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.
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.
/* 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 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:
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.
Your first name:
Your family name:
Your location (city, country):
Your Email address:
Top of Page