Commenting Routines
- Keep comments close to the code they describe
- Describe each routine in one or tow simple sentences at the top of the routine
- Document parameters where they are declared (good exception to endline comment rule)
- Take advatage of code documentation utilities (ex: JavaDoc)
- Differentiable between input and output data
- Document interface assumptions
- Comment on any routine limitations
- Document any global side-effects (IE if the routine modifies global data)
- Document the source any algorithms that are used (give credit where credit is due)
- Use comments to mark parts of your program for quick searches, see JavaDoc conventions for more details
Short Example:
/**--------------------------------------------------------
Name: SPreaderAux::compute_bounding_box
Desc: Computes min/max bounds for vertices/triangles
---------------------------------------------------------*/
/*virtual*/ bool SPreaderAux::compute_bounding_box()
{
...
}
Long Example:
/**--------------------------------------------------------
Name: SPreaderAux::compute_stats
Desc: Compute statistics for Vertices and Triangles
Notes:
1. Assumes stream has already been properly opened
2. Assumes stream is properly positioned to read
the first command (vertex/triangle) from stream
(IE any header info has been read...)
3. User should either close() the reader
or restart() reader after computing stats
---------------------------------------------------------*/
/*virtual*/ bool SPreaderAux::compute_stats()
{
...
}
--
ShawnDB - 16 Jun 2008
to top