Comments

* Every file that contains source code must be documented with an 
  introductory comment that provides information on the file name and its 
  contents. 
 
* All comments are to be written in English. 

* Write some descriptive comments before every function. 

* Use // for comments. 

* It is necessary to document source code. This should be compact and easy
  to find. By properly choosing names for variables, functions and classes 
  and by properly structuring the code, there is less need for comments 
  within the code.
 
* Note that comments in include files are meant for the users of classes, 
  while comments in implementation files are meant for those who maintain 
  the classes. 

* Comments are often said to be either strategic or tactical. 
  * A strategic comment describes what a function or section of code 
    is intended to do, and is placed before this code. 
  * A tactical comment describes what a single line of code is 
    intended to do, and is placed, if possible, at the end of this line. 
    Unfortunately, too many tactical comments can make code unreadable. 
    For this reason, it is recommended to primarily use strategic comments
    unless trying to explain very complicated code. 

Example 1: Documentation of a File 

//
// File: rational.cpp
// Description: This program reads, writes and does mathematical 
// operations on rational numbers. A rational number is defined as a 
// fraction whose numerator and demoninator are both integers.
//
//  Author: Bunny Tjaden
//  Login ID: bt14002
//  Due date: February 2, 2002 
//  Est. Time: 2 hours      (estimate of time to complete)
//

Example 2: Strategic and Tactical Comments
 
// THE NEXT TWO LINES ARE STRATEGIC COMMENTS 
// This function does some complicated things. It works like this:
// yadah-yadah-yadah . . .
int insanelyGreatAndComplicatedFunction ( int i )
{
   int index = i++ + ++i * i-- - --i   // THIS IS A TACTICAL COMMENT
   return index;
}

Functions

* A function should do ONE thing, and do it very well. QED


The information in this file was in large part adapted from:
       http://www.multimania.com.pierret/cpp2.htm