Code Quality Guidelines (Draft)

The following is a list of **code quality** deductions we might apply on your code. You should expect that additional "correctness" deductions might apply (particularly for concurrent code), but this is intended to be a complete list of deductions for the style of your code. # 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 `compute-cpu2` with `clang-with-asan` - At least one warning is generated when the code is compiled on `compute-cpu2` with `clang-with-asan`