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 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.

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

/*
    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()
*/