Chapter 2

• One of our goals is to learn how to document programs.
  • Demonstrate understanding of proper program documentation.
• As programs become large, it is difficult to understand the program.
  • Proper documentation helps to resolve this issue.
• We document programs in a number of ways
  • Direct comments.
  • Self documenting code.
  • Whitespace and blank lines.
  • Following a coding convention.
  • Proper use of programming constructs.
• Much of this information is contained in the Local Programming Style Guide
• Direct comments
  • Direct comments are statements placed in the code that are ignored by the compiler.
  • There are two types.
    • C style comments
    • C++ style comments
  • C style comments.
    • These comments start with a /*
    • And continue until you encounter a */
    • They can go across multiple lines.

    • /* 
      this is a C style comment.
      It covers all of the text 
      until the next line
      */ 

    • I use these for larger comments
      • A block at the beginning of the program to identify what is going on.
      • A large block before a complex chunk of code that goes across multiple lines.
    • I also use these for commenting out code.

      • int main() {
            int age;
        
            cout << "Enter your age => ";
            cin >> age;
        
            /*
            if (age > 15) {
            } else if (age > 5) {
            } else {
            } 
            */
            cout << age
        } 

  • C++ style comments.
    • start with //
    • Go to the end of a line.
    • I use these for one line comments above a block of code.

    • // ask the user for their age.
      cout << "Please enter your age -> ";
      cin >> userAge;
      
      // compute the user's status based on age.  

  • When do you use comments.
    • Comments should provide identifying information.
      • Author
      • Program information (assignment number, course, ...)
      • Collaborators
      • Copyright information.
    • Comments should be used to identify or explain difficult code sections.
    • But do not comment every line of code.
  • What should comments contain
    • Useful descriptions of the code.
    • High level discussion of code.
    • But not a restatement of the code.
  • See Comments and Documentation for more elaboration.
• Identifiers
  • Use of well named identifiers.
  • good
    • ageOfStudent
    • numberOfCars
    • gradePointAverage
  • bad
    • a
    • noc
    • grdptavg
  • You should be able to read the equations.

  • numberOfStudents = totalHeadCount - numberOfFaculty - numberOfStaff; 

  • See Conventions for Identifiers for more information.
• Whitespace and blank lines.
  • See Use of Whitespace in Programs
  • One statement per line.
    • But break lines longer than 80 characters.
  • Use plenty of whitespace.
  • Blank lines between major code sections.
• Use proper indentation
  • See Indentation
  • Every time you have a {
  • Indent 4 to 8 more spaces.
  • Stop indentation with a }
• Pay attention and copy
  • Your instructor's examples.
  • Examples in the book.
• Do not write sloppy code then clean it up.
  • The style actually helps you understand your code.
  • And will prevent errors.