C++ Comments			    Bob Walton, 7/16/96

C++ introduces a new kind of comment:

  //<any text not including an end-of-line><end-of-line>

That is, two slashes, //, introduce a comment that ends
at the end of the current line.

All declarations of functions, and all declarations of
global data or members of globally used classes, must be
commented.  The comments should tell how to use the data
or function or member, so programmers can use it WITHOUT
reading the code that sets the data or implements the
function.

Three styles of comment are:

  int my_boolean_switch;
      // This switch is on if the thing I like best is
      // ready.

and

  // This switch is on if the thing I like best is
  // ready.
  //
  int my_boolean_switch;

and

  int my_boolean_switch;	// This switch is on if
				// the thing I like best
				// is ready.

The first or second form is preferred in places where
the comments tend to be more than a few words.  The
third form is preferred in places where many items in
a row have short comments of a few words each, and a
tabular organization can be maintained.

There are other commenting styles that make sense.  The
C comments /* */ are also usable in C++, but they are
discouraged because they are dangerous: programmers have
been known to write code such as:

  x = FAMOUS * y;	/* Multiply by famous factor. /*
  x = x + JOHNSON;	/* Add Johnson's coefficient. */

and wonder why the addition never got done.