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.