====== Comments and Documentation ======
This guide provides general guidelines for the use of comments and documentation.  Directions given by your instructor supersede these instructions.

The purpose of comments and documentation is to allow readers of the program to understand what is happening.  This could be the original programmer, someone who has taken over maintenance of the code, or even a casual reader of the code.  Documentation generally falls into two categories, comments and self documenting code.

===== Self Documenting Code =====

Self documenting code is achieved in a number of ways.  The most apparent is appropriate selection of identifiers.  This is supported by proper use of white space and indentation as well as the general structure of the code.  Many of the guidelines in other sections of this document describe conventions which help programmers provide self documenting code.

===== Use of Comments =====

==== Comments at the Beginning of a File ====

All files should begin with identification information.   This should answer the questions who created this file and why.  While style may vary from programmer to programmer, a general guideline is to use a block comment at the top of the file providing the following information
  * Programmer Name
    * List any collaborators
  * Class and Section
  * Date
  * Assignment identification information
    * Program Name
    * Program Number
  * A narrative describing the contents of the file
  * Special notes
    * Additional features
    * Items not implemented

<code c++>
/*
    Program 2, Mad Libs
    Programmer: Dan Bennett
        Collaborators: I had extensive help from John Hoggard, Doug Puharic and Amanda Porter
    Class: CSCI 130
    Date: September 2020
    Short Description:  This program simulates a Mad Lib game.
    
    Narrative:
        This program will simulate a Mad Lib game.  The user is first prompted for a number of words or 
        phrases.  The program will then incorporate these phrases into a hard coded story.
        
    Special Notes:
        * The user is only able to supply a single word for each prompt.  If they type more than one word,
          that will be ignored with cin.ignore()
*/
</code>
==== Comments Before Functions ====

Functions should be proceeded by a block comment which describes at minimum
  * A narrative describing the purpose of the function
  * The input and output to the function
    * Please note, this is a description of the parameters
    * Input represents values passed into the function
    * Output represents values returned or passed out of the funciton
    * Input/Output represents values that are passed in, but may be changed
  * Pre/post conditions for the function
  * Special notes if required
    * Explain any special algorithms
    * Source of the function

<code c++>
/*
    Function: GetWord
    
    This function is responsible for interacting with the user to get a word that matches the given
    description.  The function will ignore any extra input on the same line as the word.
    
    Input: 
        description: a string which describes the word required
                    example: "a noun"
    Output: 
         word: the word the user has provided
         
    Notes: This function uses cin.ignore to ignore all input after the first word.
           A word is described as any collection of non-white space characters.
           
    Preconditions: none
    Post conditions: at least one word has been read from the input stream
                    any input after the first word, up to 1000 characters will be ignored.
</code>

==== Comment Placement in Code ====

Single line comments should be placed before sections of code which need explanation.

Comments should begin in line with the code which is being documented:

An acceptable example:
<code c++>
    // Read the input from the user and ignore any extraneous output
    cin >> word;
    cin.ignore(1000,'\n');
</code>

An unacceptable example:
<code c++>
// Print a line of the story filling in the blank
       cout << line1Part1 << nounResponse << " " << line1Part2 << endl;
</code>

Comments should generally not be placed on the same line as code.  This guideline may be violated when declaring variables.

The following example is not acceptable.
<code c++>
       cout << endl;    // done with output, print an endl
</code>

Use comments to supplement the understanding of major sections of code.  Only rarely should comments be used on every line of code.  The following is not an acceptable use of documentation.
<code c++>
// Get the noun from the user
noun = GetWord("a noun");
// Get the adjective from the user
adjective = GetWord("an adjective");
// Get the action verb from the user
actionVerb = GetWord("an action word");
</code>

The code above is mostly self documenting due to identifier choice, so a single comment would be more appropriate
<code c++>
// Get the words from the user
noun = GetWord("a noun");
adjective = GetWord("an adjective");
actionVerb = GetWord("an action word");
</code>


Finally, most comments in code should employ a c++ style line comment.  This allows the programmer to comment out large blocks of code with c style comments.

==== Comment Contents ====

Comments should describe the code, however comments should not repeat the code.

An acceptable example:
<code c++>
// use the Pythagorean theorem (a^2+b^2 = c^2) to find the length of the third size.
hypot = sqrt(sideA * sideA + sideB * sideB)
</code>

An unacceptable example:
<code c++>
// c = sqrt(a*a + b*b)
hypot = sqrt(sideA * sideA + sideB * sideB);
</code>
In the above example, the comment provides NO additional information.  It is a duplication of the code.  This could be very detrimental if the original code was in error and later corrected, but the comment was not updated.  In that case, a future reader of the code would be further confused by the comment.


In general, comments should support a knowledgeable programmer.