C++ commenting

What is absolutely necessary

1. Header Your comment header should include your user name, real name, assignment number, due date, and possibly additional information, such as program name, version number (for those continuously evolving programs), output format, and date started. An example would be something like:

     /*
     jcaesar
     Julius Caesar
     Assignment #4
     due 03/15/-49
     */ 

2. Function comments Give a short description of what the function does. Omit it if the function is obvious, like

   double sqr( double base )
      {
      return base*base;
      } 

   Comment the function if it is recursive, or if it changes the actual arguments passed to it (uses call-by-reference with side effects).

3. Occasional Line-by-Line comments The C++ one-line comment, //, makes it much more convenient to include short descriptions of what a line does, such as:

     x = ( -b+sqrt(b*b-4*a*c) ) / (2 * a); //positive quadratic root 
   

   They are especially good at clearing up what an if-else statement is checking. Do not use comments to rephrase your code. The following is not at all helpful, and in some cases it makes code harder to read:

     for ( i=0 ; i<10 ; i++ ) // loop from 0 to 9 with i
         cout << i;           // print i 

Notes:

Copyright (c) HMC Computer Science Department. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.''