Code Documentation Recommendations

·        Maintain a mainpage.h file in the package's src directory.  This file contains a general description of the package and is used as the index page for Doxygen output.

·        All class declarations must be preceded by a Doxygen style comment block describing the class.

·        Doxygen style comments immediately precede class, method, and member declarations.

·        Doxygen style comments normally reside within the header file before declarations.  When there is no header file, Doxygen comments reside with the declarations within the implementation file.

·        Implementation files contain standard C++ comments, where the form '//' is preferred over '/* .. */'.  Each important member function should contain a standard comment block of the form:

                        // Purpose and Method:  [include the physics if appropriate]
                        // Inputs
                        // Output
                        // Dependencies
                        //
                        // Restrictions and Caveats:  e.g. "This doesn't work off-axis"

·        Do not bother to document obvious members or methods such as default constructors and get and set routines.

·        Use white space to set off comment blocks, rather than divider lines.

·        Maintain a release.notes text file in the package's doc directory noting major revisions and tags.

·        When checking in code to the CVS repository, provide modification details within the log message.  The log messages are automatically stored within a ChangeLog file and will be used as the modification history.

·        If images are inserted into the Doxygen comments, the image files should be stored within the package's doc/images directory.

·        Keep comments up-to-date when modifying code.