How I may help
LinkedIn Profile Email me!
Call me using Skype client on your machine

Reload this page 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:

  • Summary
  • JavaDoc
  • Java Source notes
  • Your comments???


    Site Map List all pages on this site 
    About this site About this site 
    Go to first topic Go to Bottom of this page


    Set screen 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.


    Go to Top of this page.
    Previous topic this page
    Next topic this page

    Set screen Java Documentation

      webpage article 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.

    Go to Top of this page.
    Previous topic this page
    Next topic this page
    Set screen
      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 version 2.3 provides a basis for reviewer comments
      Unit Test Plan at version 1.3
      Developing using Eclipse 2.1 IDE

    Go to Top of this page.
    Previous topic this page
    Next topic this page

    Set screen 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:


      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.

    Go to Top of this page.
    Previous topic this page
    Next topic this page

    Portions ©Copyright 1996-2010 Wilson Mar. All rights reserved. | Privacy Policy |


  • Exception Handling
  • Java Beans and J2EE
  • Design Patterns,
  • Data Types, Strings, Escape Characters, Dates
  • Programming Logic, Operators, Functions, Threads, AWT/Swing, Events, I/O
  • Applications Development
  • On the web

  • How I may help

    Send a message with your email client program

    Your rating of this page:
    Low High

    Your first name:

    Your family name:

    Your location (city, country):

    Your Email address: 

      Top of Page Go to top of page

    Thank you!