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