Comments

• Remember, one of the goals of the class is to produce a program with proper documentation.
• There are several ways we document code.
  • External documents
  • Comments
  • Self-documenting code
  • Code formatting
• External Documents
  • Your design document is an example of an external document
    • Would this be of any value while we are writing the code?
    • Would this be of any value after the program is in use?
    • Note, on large projects, you will probably be required to update these documents as work progresses.
  • Other documents include
    • Specification and requirements documents
    • Manuals/how to use documents
    • Production and Maintenance records
    • Bug requests
  • If you stay with us, you will learn much more about this in Software Engineering.
• Comments
  • Comments are part of the program file.
  • That the compiler ignores.
  • In c++ there are two types of comments.
  • C style or block comments
    • begin with a /*
    • End with a */
    • Can be multiple lines long
    • Used for
      • Removing, but not deleting blocks of code
      • Creating multi-line comments.
        • Like at the beginning of a file.
    • I use c style comments at the beginning of my code to supply information about the program
      • Name
      • Project identification and description
      • Date written
      • Collaborators
    • Add a block comment to the beginning of our project.
  • C++ style comments
    • These start with // and go to the end of the line.
    • Comment out a single line of code
    • Describe the block of code that follows.
    • I use these all over the place.
  • More information on comments can be found here
• Self-documenting code
  • Anything we name, constants, variables, and later functions, data structures and more is named with an identifier.
  • We use the principal of using meaningful identifiers.
    • This means that you can tell the use of the identifier from the name.
  • Use white space
    • I use blank lines to separate ideas.
    • I use plenty of space in the statements themselves.
• Code formatting
  • We have other conventions for identifiers
    • constants: WORD_WORD_WORD
    • variables: wordWordWord
    • functions: WordWordWord
    • Look here for more information.
  • Indentation
    • Every time you start a code block: {
      • Indent four or five spaces.
    • When you close the block : }
      • Stop indenting.
• Our local style follows that of the book.
  • And is documented here
  • I will deduct points to failing to follow the style guide.
• Other style guides
  • google
  • AWS guide.