CS 311 Fall 2024  >  Coding Standards

CS 311 Fall 2024
Coding Standards

The following standards apply to all source code (including header files) turned in this semester.

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/execute, 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 execute 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 must be neat and readable, with consistent indentation where appropriate and proper use of whitespace.
  2. All comments in the code must be correct.
  3. Code must conform to standard conventions, with appropriate use of programming-language constructs.
    • For C++ this would involve the conventional use of header and source files, const-correctness, making overloaded operators member or global as appropriate, and passing parameters using appropriate methods.
  4. Code must not perform any actions visible to the client code or the user, other than those in its specification.
    • Debugging printout is a great idea, but before you submit your work, turn it off.
    • Avoid unnecessary creation or alteration of data visible to the client code.
  5. Code must not place any arbitrary limits on data.
    • An example of an arbitrary limit would be requiring a line typed by the user to be at most 1000 characters long.
    • 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.
  6. Code must actually perform the required computations. Hacks that only work with the exact input given by a test program will not be counted as fully correct.
  7. Avoid unnecessary or duplicate code.*
    • In C++, automatically generated member functions should be used whenever possible.
    • In C++, constructors should use member initializers appropriately.
    *There is one situation in which this standard may be violated: when writing both const and non-const versions of a C++ member function, the function bodies of these two versions may be identical.

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 assignments.
  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 is to 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 the 2017 ISO standard or a later ISO standard. It must compile and execute with a standard-conforming build system.
  2. At the beginning of every file must be comments indicating the file’s name, author(s), last revision date, and purpose. (The purpose comment does not have to be very long. Something like “Header for class Foo” is generally fine.)
  3. Only include/import required headers, and avoid namespace pollution.
    • 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 assignments later in the class will need to meet the following standards. Students will be notified when these standards must be met.

  1. 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.
    • Postconditions are not required to be documented.
  2. Before every class definition there must be comments indicating class invariants.
    • If there are no class invariants, then write “Invariants: None”.
  3. 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”.)
  4. If a function is a template or a member of a class template, then indicate in a comment whether the function is exception neutral, and whether it throws any additional exceptions.
  5. If a function is a member or friend of a class, then its exception safety guarantee must be documented.