Coding Standard

Identifying all the components contributing to a well-designed program is challenging. The following list serves as a starting point and is used to evaluate class projects. While there may be some exceptions, they are not typical and should not overshadow the general guidelines. Consider how these guidelines apply when reviewing a program rather than focusing on potential exceptions. The checklist will be extended as the semester progresses.

• Files and Directories
• Overall Program
• Indentation
• Spacing
• Naming
• Statements
• Functions
• Parameter Types
• Return Types
• Comments
• std::string
• Debugging Output

Files and Directories

Only source files belong in the repository:

• Source-code files: .cpp, .hpp
• Build definition files: CMakeLists.txt, .cmake, .cmake.in, .json, Makefile (not generated by CMake)
• Documentation: .md, .txt
• Example input files

Generated files do not belong in the repository:

• Object files: .o, .obj
• Executable files: .exe, program
• Results of build, CMakeCache.txt, CMakeFiles

Generated files take a lot of filespace and prevent others from easily cloning the repository and building.

Overall Program

• Every source-code file needs a header comment, including the filename, a description of the contents, and possibly copyright and license. Leave developer names and dates out of header comments. Exception: copyright years
• Leave a single blank line after the header comment
• Every include file (.hpp) needs an include guard
• Every implementation file (.cpp) must include the associated .hpp file first before any other include files
• Never include a .cpp file. It is not the answer if you have to include a .cpp file to get your program to compile/build. There are rare circumstances where this is needed, but there are no situations in this course.

• Do not use using namespace std;.

  using namespace std; cin >> n;

  Instead, use the prefix for everything in a namespace:

Indentation

• Indentation follows the flow of control
• Indentation of 4 spaces for each control-flow level Coding Style
• Use spaces, not tabs
• End the file with a single newline

Spacing

Naming

• Proper and consistent naming is critical to good programs and may be the most critical design decision that you make
• Use terms from the problem domain as much as possible
• Naming should improve as you gain more experience with the problem domain and the code

• Use the following naming convention:

  Category	Semantics	Convention	Example
  Classes	things not actions	PascalCase	class Token
  Fields/Variables/Parameters	things	camelCase	int totalSize;
  C++ Methods/Functions	actions	camelCase	void sortNames();
  C Functions	actions	under_score/camelCase	srcml_archive_get_unit()
  Constant scalar values	things	UPPERCASE	const int MAX_SIZE = 100;
  C-Preprocessor/cpp variables	things	UPPERCASE	#ifndef INCLUDE_XML_HPP

• Exception: Adding or integrating into an existing library, use the naming convention of the library. E.g., if adding a new Container type that fits into std::vector, etc., follow that naming convention.
• Some domain terms are all uppercase, e.g., XML. So a variable relating to that domain can use that form, e.g., XMLBuffer

• Single-letter variable names are not to be used, except in certain, well-understood situations:

  Name	Purpose
  i, j, k	loop-control variables
  c	general character
  s	general string
  n	general int
  x	general double

Statements

• Initialize temporary variables (those with local scope) when declared whenever possible.

  Initialization in Declaration (preferred)	Separate declaration

• Exception: Temporary variables initialized as an argument in a call:

• Use int as the standard C++ integer type. Possible exceptions: size_t, std::size_type
• Use double as the standard C++ floating-point number type. There is hardly any reason to use float.
• Separate statements into sections (hunks) with a (single) blank line between the sections

• Comment each section of code on the line before

• Make each section cohesive. All statements in a section should be related to each other
• Use const whenever possible
• Use auto when initializing a declaration that includes a call, e.g., auto pc = buffer.begin()

• Use an explicit type instead of auto when initializing with a literal value to make certain you get the intended type

• Prefer pre-increment over post-increment, i.e., prefer ++i; over i++;. Pre-increment is easier to understand, explain, and implement, e.g., post-increment is often implemented using pre-increment, especially when these operators are overloaded:

  Pre-increment Implementation	Post-increment Implementation

  This also applies to pre-decrement and post-decrement

• Prefer pre-increment over post-increment in for loops. Using pre-increment in a for loop does not mean that the increment occurs before the loop.

  for-statement	Equivalent while-statement

• Favor the range-based for-statement instead of direct indexing (or iteration).

  Range-based for (preferred)	Direct Indexing

Functions

• All functions must be declared in an include file (.hpp) and defined in an implementation file (.cpp) unless specifically told otherwise.
• All functions require a comment before both the declaration and the definition.
• Favor Doxygen-style function comments. Look at the course examples for style. Useful markup includes:
  • @param For each parameter
  • @return For the general return purpose
  • @retval Specific return values, e.g., error or status codes

  There is much more, so feel free to experiment. However, be consistent.

• Do not use the inline specifier. First, the compiler can ignore it. Second, the compiler automatically inlines small functions. Third, it is overused. The inline specifier has good purposes, but only in specific cases and not in this course. Note: Do not confuse the general programming term "inline a function" or "inline a method" with the inline specifier.

Parameter Types

Use the following tables for type T:

Examples:

• Passing an IN parameter object by value instead of by const reference can have a substantial efficiency penalty, i.e., Quick Bench: std::string vs. const std::string& IN parameter, especially when passed repeatedly.
• Note that the const of a value (not the const of a reference), e.g., const int, is not in the list. The reason is that the const is an unnecessary restriction for the function/method definition (implementation) and does not change the arguments allowed (caller).
• If you are passing an object and make a copy internally, then pass by value (T)
• Will discuss rvalue-references, e.g., std::string&&, separately

Return Types

For free functions:

• In a few cases, you may want to return a reference to a field so it can be changed externally to the class. In this case, use T&. Be very careful about this. It's safer to send a copy and maybe just as efficient.
• Will discuss rvalue-references, e.g., std::string&&, separately

Comments

The following applies to all comments except file header comments.

• Terms to leave out of comments:
  
• Phrases referring to program structure to leave out of comments:
  
• General phrases to leave out of your comments:
  

std::string

Prefer the default and methods common to a container:

std::string_view

The new string type std::string_view was an addition to C++ in C++17. It allows you to efficiently refer to parts of a pre-existing std::string or a c-string char* without making a copy. When used as a parameter with a c-string argument, e.g., "abc", it does not create a std::string. It has many of the same methods as the std::string.

If an IN parameter is used, it is typically passed by value instead of const reference as it is small.

Debugging Output

Write debugging/tracing messages to std::cerr, not std::cout:

• The program already uses std::cout for output, so this gives a way for the user to separate the intended output from error messages
• Especially important during debugging. The output std::cerr is not buffered, while std::cout is. If your program crashes, any unbuffered output may be lost. So, you may not see your debugging messages.