CS 311 Fall 2020  >  Coding Standards


CS 311 Fall 2020
Coding Standards

The following standards must be followed on all source code, including header files, turned in as CS 311 projects.

Of first importance are the following.

Code that does not meet the above standard will not be graded.

If you cannot get code to compile, then I am happy to help you figure out what the trouble is. However, for code turned in for a grade, the above requirements are absolute; if you cannot compile your code, then there is no point in turning it in.

1. High Quality Code

Code must be of high quality. In particular:

  1. Code should be neat and readable, with consistent indentation and proper use of whitespace.
  2. Code should include explanatory comments, as appropriate, and these comments must be correct.
  3. Files must be organized in accordance with standard conventions.
    • In C++, split code appropriately among header and source files, and use #include in the proper places, and #ifndef to avoid multiple inclusion.
  4. Unnecessary or duplicate code should be avoided.
    • In C++, silently written member functions should be used whenever possible. When they are used, the fact must be noted, either in a comment, or via an “= default;” declaration (the latter is preferred).
    • In C++, constructors should use member initializers appropriately.
    • One exception. When writing both const and non-const versions of a C++ member function, the function bodies of these two versions may be identical.
  5. Code should not perform any actions visible to the client code or the user, other than those in its specification.
    • In particular, avoid debugging printout in the turned-in version of your code.
  6. Code should not place arbitrary limits on the data it is given.
    • For example, if a function is given a string, then it should not restrict the length of that string to (say) 1000 characters, unless the specification indicates that this should be done.
    • On the other hand, if, for example, a function is given an integer, in a context in which negative values do not make sense, then the function may require the integer to be nonnegative.
  7. All functions should pass their parameters and return values in appropriate ways, and be defined in the appropriate place (e.g., inside a class? outside?).
    • In C++, overloaded operators must be appropriately declared as member or global.
  8. Appropriate use should be made of programming-language constructs that deny privileges.
    • In C++: const, private, etc.

2. Using the Work of Others

It is understood that very little programming is done from scratch; new programs are based on old programs, often written by others. However, the following standards will apply.
  1. Submitted code must be largely your own work—or the work of your group members, for group projects.
  2. It is expected that you will only turn in code you understand, regardless of who wrote it.
  3. If a portion of your code was written by someone else, or if a portion of your code is a modified version of someone else’s work, then that person must be acknowledged in a comment in your code. This includes code written by your instructor.
  4. Any use of someone else’s code must be in accordance with any licenses that accompany the code.

3. Specific Standards

  1. All source code must be in C++, following either the 2017 or the expected 2020 ANSI/ISO standard. It must compile and execute with a standard-conforming build system.
  2. At the beginning of every file should be comments indicating the file’s name, author, date, and purpose.
    • Note. The purpose comment does not have to be very long. Something like “Header for class Foo” is generally fine.
  3. If a function has preconditions, then these must be documented in comments just before at least one of the function’s declarations. For a member function, class invariants do not need to be included in the listed preconditions.
    • Note. Postconditions are not required to be documented.
  4. Before every class definition there must be comments indicating class invariants.
    • If there are no class invariants, then write “Invariants: None”.
  5. Only required headers should be included, and namespace pollution should be avoided.
    • Do not write “using namespace std;”.
    • Avoid the “.h” system headers. For example, use <cmath> instead of <math.h>.

4. Additional Standards

In addition, some projects later in the class will need to meet the following standards. Students will be notified when these standards must be met.

  1. Requirements on template parameter types must be documented.
  2. If a function is not a template and not a member of a class template, then the exceptions it throws must be documented. (Often, this will be simply “Does not throw”.)
  3. If a function is a template or a member of a class template, then indicate whether it is exception neutral, and whether it throws any additional exceptions.
  4. If a function is a member or friend of a class, then its exception safety guarantee must be documented.