cs24-21faCode Quality Guidelines

Introduction to Computing Systems (Fall 2021)

The following is a list of code quality rules that the linter will check for. Each project will lose points for not passing the lint tests in their entirety (some more than others).

Formatting

• A file uses mixed or poor indentation (tabs and spaces)
• A file has at least one line that is more than 90 characters
• A file has inconsistent brace styles
• A block of code has a missing space after a keyword (e.g., if, else, while, …)
• A single line has more than one statement on it
• A one-line loop or conditional does not use braces
• An expression or conditional uses an assignment as a sub-expression

Variables

• A variable is not named with snake_case
• A variable is not properly descriptive
• A variable is not declared as close to its usage as possible (e.g., variables are all declared at the top of a function)
• A variable type like int or long is used instead of one that specifies the size explicitly (e.g., int32_t, size_t)
• A magic number is not appropriately abstracted from the code as a const variable or macro

Macros

• A macro is not named with SHOUTING_CASE
• A macro is misused or abused (We expect almost all usages of function macros to fit this definition. You have been warned.)

Functions and Decomposition

• A function is not named with snake_case
• There is no significant attempt at decomposing functions into helper functions that each do one thing
• There is a significant amount of code duplication (this is usually any more than ~10 lines)
• A function exits the program on a potentially recoverable error (an alternative is to return from a helper function with an error code)
• The return value of a function that could fail is not checked

Modules and Types

• A type definition does not end with _t or is not in snake_case
• A header file misuses include guards
• A C file that should have a corresponding header file (e.g., it has a public interface) does not have one or a public function is missing

Commenting

• A TODO, block of dead code, or block of commented out code is left in the final submission
• A block of code is unclear and not commented
• A comment does not describe the actual behavior that the piece of code has
• A comment is useless or uninformative
• A public function is entirely undocumented

Compilation

• The code does not compile on labradoodle with clang-with-asan
• At least one warning is generated when the code is compiled on labradoodle with clang-with-asan