Code quality standards

This course will teach you how to write clean code. Clean code makes bugs less frequent, and easier to detect when they do occur. It also makes it easier for others to help you with your code. In industry, writing clean code will ensure that anyone on the team and understand and maintain it. This increases the value of your code—and you—to the company. Follow these guidelines all the time—from the beginning.

dead code

Unused functions

never

Rule: Functions that are never called from within a file and are not part of the public interface (i.e., required for homework) must be removed or commented out.

✗	int main() { return EXIT_SUCCESS; } void _foo() { // not called by main(…) or anything else // ... }

✓	int main() { _foo(); return EXIT_SUCCESS; } void _foo() { // ... }

Reason: Unused functions (including old versions) cause confusion. You may think you're debugging the one that gets called and the realize you're debugging something that never gets called at all.

Unreachable code

never

Rule: Remove or comment out any statements that can never be reached.

✗	if(1 == 0) { doSomething(); // will never get here!!! }

Unused variables

never

Rule: Remove or comment out variables that are never read (and thus have no effect on program execution).

✗	int foo(int a) { int b = 1; // never read!!! return a * 10; }

Useless assignments

never

Rule: Remove assignment statements that can have no effect on program execution.

✗	int foo() { int a = 0; a = a + 10; // no effect!!! a = 20; return a * 10; }

variable scope

Loop index

limit scope to loop

Rule: Declare and initialize for loop counter in the for statement.

✓	for(int i = 0; i < 5; i++) { printf("%d\n", i); }

✗	int i; for(i = 0; i < 5; i++) { printf("%d\n", i); }

✗	int i = 1; for(; i < 5; i++) { printf("%d\n", i); }

Exception: Occassionally, you may need to use the counter in code below the for loop. In that case, declare and initialize outside the for loop (like Bad #1 above) and explain why in a comment.

✓	int divisor = 1; // will be used after the loop for(; divisor < n; divisor++) { … } return divisor;

Global variables

constants only

Rule: Do not use global variables, except for constants, unless there is a clear and compelling reason.

✗	#include <stdio.h> int g = 0; int main(int argc, char* argv[]) { g += 1; … }

✓	#include <stdio.h> const int NUM_FEET = 2; int main(int argc, char* argv[]) { … }

Note: In ECE 26400, we will tell you if there is a clear and compelling reason. Otherwise, do not use global variables, except for constants (declared with const).

variable initialization

Declare where you initialize

usually

This section was revised to clarify on 2/6/2020.

Rule: Declare local variables on the line where they are first assigned to, or as close as possible.

✗	int i; i = 0;

✓	int i = 0;

✗	int i; for(i = 0; i < n; i++) { ▒▒▒▒▒▒▒▒▒▒; }

✓	for(int i = 0; i < n; i++) { ▒▒▒▒▒▒▒▒▒▒; }

Exception: In rare occassions, there may be no meaningful value to initialize a variable to. Don't initialize to a meaningless value just to comply with this rule, since that could prevent Valgrind and/or GCC from warning you if you try to access an uninitialized value.

✗	int a = 0; // 👎BAD – Do not initialize to a meaningless placeholder value. if(▒▒▒) { a = ▒▒▒; } else { a = ▒▒▒; } foo(a)

✓

int a;  // 👌
if(▒▒▒) {
  a = ▒▒▒;
}
else {
  a = ▒▒▒;
}
foo(a)

This is okay because a will be initialized in one of ≥2 subscopes (i.e., the if block or else block).
a cannot be declared inside the if and else block because it will be used below the if/else.
Do not initialize to a placeholder (e.g., 0), unless that would be a legitimate default that should be kept in some cases.

Exception: You cannot declare a variable inside a switch/case statement.

✗	switch(▒) { case ▒: int a = 5; // 👎 Compiler error foo(a); default: ▒▒▒▒▒▒▒▒▒▒; }

✓	int a; // 👌 switch(▒) { case ▒: a = 5; foo(a); default: ▒▒▒▒▒▒▒▒▒▒; } A variable that is first set inside a switch/case should be delcared immediately before the switch.

Note: This is consistent with Google's C++ Style Guide under Local Variables.

Array initializers

use

Rule: Use array initializers where possible and appropriate

✓	int numbers[] = {1, 2, 3};

✗	int numbers[3]; numbers[0] = 1; numbers[1] = 2; numbers[2] = 3;

Reason: Array initializers are clearer to read, and avoid certain types of bugs (e.g., numbers[3] = 4 for an array of size 3.).

Note: This is consistent with Google's C++ Style Guide under Local Variables.

Struct initializers

use

Rule: Use named initializers where possible and appropriate.

✓	struct Point point1 = {.x = 1, .y = 2};

✗	struct Point point1; point1.x = 1; point1.y = 2;

✗	struct Point point1 = {1, 2};

Reason: Struct initializers are clearer to read. They also prevent mistakes where programmers sometimes forget to initialize one field, or perhaps edit the code later and inadvertently delete part of the initialization. Bad #2 is actually fine in earlier versions of c (e.g. c89), but the new syntax shown as Good prevents errors where you get the order wrong.

Struct object on the heap

use

Rule: Use compound initializers to initialize struct objects on the heap.

✓	Node* node = malloc(sizeof(node)); node = (Node) { .value=10, .next=NULL };

✗	Node* node = malloc(sizeof(*node)); node -> value = 10; node -> next = NULL;

Reason: Initializing an object is essentially a single action. Keeping it in a single statement reduces the chance that you forget one part of it, or that you move part of it but not the rest.

names – format conventions

Global constants

ALL_CAPS

Rule: Use all caps with words separated by underscores

Spring 2023 ECE 264 :: Purdue University

Code quality standards

dead code

variable scope

variable initialization

names – format conventions

naming – numbers and strings

naming – functions

naming – struct types, objects

cast operator

structure

whitespace

explanatory comments

test code

constant expressions

Related resources

Updates