Style Guide for CMSC 214

Updated: Wed Sep  3 22:50:24 EDT 2003
                
Comments

* Every file that contains source code must be documented with an
  introductory comment that provides information on the file name and its
  contents.  Included in this comment should be your full name, login ID,
  your section number, the project number and an estimate on the amount  
  of time it took to complete the file.
  
* All comments are to be written in English.

* Write some descriptive comments before every function.

* Use // for comments.

* Indent code neatly and uniformly

* After every } used in a for or while loop, if or else or if-else put
  // end [name of control structure]

  example:

  for (i = 0; i < n; i++) {
    if (array[i] > 0) {
      cout << array[i];
    } // end if
  } // end for

* 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: bt14001
//  Due date: Sept 3, 2003
//  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

Using code from a textbook or online coding examples
  
* While this is not encouraged, sometimes we find "inspired" pieces
  of code that accomplish something in a very unique and "better" way.
  If you adapt this code in your projects you should protect yourself
  from plagiarism charges by crediting the source (see below) and IN
  ADDITION you must notify in writing (via email) your instructor of
  the code which you "adapt/use".

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