Coding style and code clarity

This document specifies the required coding style for EEE243 and GEF243. Code must always be written to maximize clarity for a reader. This includes good names, consistent formatting, and appropriate hierarchical structure. If you’re thoughtful about your code structure and naming, you will remove the need for most inline comments.

To illustrate the requirements of this style guide, we have provided examples of badly-written code, less-badly-written code and well-written code. All three programs accomplish “the same thing”, but only the well-written example fully conforms to the coding standard.

General formatting and indentation

General formatting and indentation must follow the default CLion style. You can use the auto-formatting command Code → Reformat Code or the keyboard equivalent on your system.

Requirements addressed by auto-formatting are indicated below by [auto].

Names

Names must always be chosen to clearly indicate the purpose of the item named. In the particular case of loop indices, short names like i and j are acceptable. Names must follow the following formats:

  • variables and function parameter names: lower-case, words separated with underscores, like student_name; normally nouns
  • functions: lower-case, words separated with underscores
    • where the function’s primary purpose is to compute a value, the name should be the value computed, like average_grade,
    • where the function’s primary purpose is its side effects, the name should be a verb like update_student_record
  • constants and macros: upper-case, words separated with underscores, like TICKS_PER_CM
  • structs, typedefs and enums: capitalized camel case, like StudentRecord; normally nouns

“Magic numbers”

Any meaningful number in your code must be given a descriptive constant name. Literal numbers other than 0, 1, 2, and -1 should not normally appear in the body of your code. The only exceptions are where the number has a well-understood meaning and is unlikely to change, e.g., 90 degrees.

Line length

Lines must not exceed 80 characters. Where the required statement needs more characters than that, the statement must be broken across lines intelligently to preserve a readable appearance. The automatic reformating option in CLion doe not automatically break the lines. However, you can configure CLion to help you with the line length by going to CLion preferences File > Settings > Editor > Code Style on Windows or CLion > Preferences > Editor > Code Style on Mac. There, you can set the Hard wrap at to 80 and select the * Wrap on typing * option.

Automatic line length

Braces and indentation

[auto] The opening brace goes on the same line as the block-opening statement (function definition, for, if, while, etc.). Blocks are indented. The closing brace is on its own line, indented to the same level as the opening statement.

Single statement blocks

All blocks must be surrounded by braces, even if one only statement long. For example, don’t do this…

if (count > LIMIT)
   error = true;

… do this:

if (count > LIMIT) {
   error = true;
}

File header comment

Each file must have a file header comment of the following form.

/*
 * Description of the purpose of this file or module, possibly spanning
 * several lines if necessary. Should be terse.
 *
 * Author   : Your names
 * Version  : Today's date
 */

Function comment

Each function in a .c file must have a function comment. The one exception is the main function, since a main’s description would normally just repeat the file header comment for the main file.

An example of a function comment is below. The description should be terse but informative. If there is anything “tricky” in the function’s implementation, it should be stated here. Every parameter must have a description, as must the return value if there is one.

/*
 * Drive straight forward, while displaying "Driving". Due to motor
 * inaccuracy, the actual distance driven may be different from the 
 * distance requested.
 *
 * speed: in native motor-control units
 * distance: to drive, in centimeters
 * returns: the distance actually driven, in centimetres
 */
float forward(int speed, float distance) {
  // ... etc

In-line comments

In-line comments may be included where they are necesary to clarify. Appropriate choice of names and good program structure will often make inline comments unnecessary.