CS 102 Programming Guidelines
(Thanks to Dr. Nico and Kurt Mammen from Cal Poly SLO for the inspiration for these guidelines)

Note
  1. All code you submit for credit this quarter must meet these guidelines or it may be marked down.

  2. All programs will be tested on department machines (hydra/cetus computers) - be sure your code compiles without warning and runs correctly on these machines.


Compilation
  1. The compiler is g++.

  2. Your code must compile without warning with the -Wall compiler flag.

  3. You may want to use -pedantic flag. It is suppose to present more easily understood error messages (that is a matter of debate!).

  4. You may use other compiler flags as necessary.

  5. If you use our provided makefiles for the labs, you generally do not have to worry about these.

Style
  1. No tab-characters in your source code. All reasonable text editors allow you to configure them to work this way.

  2. Use meaningful variable and function names.

  3. Do not use "magic numbers", unless the number's meaning is obvious, use #define or const as you prefer.

  4. All lines must be 100 characters in length or less (this includes any whitespace at the end).

  5. Choose a level of indentation (number of spaces) you like and use it consistantly (2-to-4 space indentation is common).

  6. Choose a bracing-style from one of the three below and use it consistantly (editorial comments included in paranthesis)
            K&R style (by the original authors of C - dense, readable, but easy to miss opening braces)

        if (condition) {
           /* body */
        }

            Newer-style (less dense, more readable due to whitespace around important logic, and harder to miss opening braces)

        if (condition)
        {
           /* body */
        }

            GNU-style (funny looking but used by code from the Free Software Foundation)

        if (condition)
          {
            /* body */
          }

  1. Always use braces for your if, while, for, do-while, and switch statements even when they are not required.

  2. Use modular design, this means:

    1. If you find yourself copying chunks of code it probably should be a function.

    2. Write small functions. Keep them short and simple. They should represent a single clearly identifiable action and their name should communicate what that action is. Only in rare occations is it necessary to have long functions.

    3. Group related functions together in separate source files.

    4. Nonexistant-to-minimal global data. If you use global data you must defend your choice with a clear and compelling arguement included as a comment block immediately above its delcaration.

  3. All functions that will be called from a file other than the one they are written in must be prototyped in a header file (.h) with the same name as the source file (.cpp) they are found in.

  4. All header files (.h) must actively prevent circular-inclusion.

Documentation
  1. Use c-style comments (/*...*/) only.

  2. All source files (.cpp) must include a header comment that lists all the functions it contains and a brief description of what they are for.

  3. All non-trivial (if you have to ask, it isn't) functions must have a comment block immediately preceding them that explains the following:

    1. What the function does.

    2. Any restrictions on its input

    3. Any gaurantees about its output

  4. All non-trivial (if you have to ask, it isn't) loops, if-else blocks, and complicated expressions inside inside a function must have a brief comment preceding it (or next to it) explaining what it does.

  5. All header files (.h) must clearly document every feature in them.