Code Inspection Rules

Golden Rule

These rules are designed to make the code easier to read and understand, more reliable, and easier to maintain. The "Golden Rule" of programming is that all the other rules listed below should support this goal.

A) Safety

A1

All array accesses must protected by an assert statement. (Exceptions are allowed only in those cases where it's absolutly impssible to determine the array bounds.)

A2

Use of the following functions prohibited:

  1. strcpy
  2. strcat
  3. gets
  4. sprintf

F) File

F1

File uses standard comment structure for the heading. (See the programming template.

F2

Files should no be longer than 3,000 lines and only unusual files use be longer than 6,000 lines long.

F3

The file compiles without warnings with full compiler warnings turned on.

P) Functions / Procedures

P1

All functions have a standard heading.

P2

All private functions are declared static

P3

All public functions have a prototype in the header file.

P4

The return type of a function does not default

P5

Function and variable definitions in header files must be declared extern

P6

Modules must include all the header files which contain external definitions of functions and variables defined in the file. (In other words if foo.h contains
    extern int foo_size;
and foo.c defines foo_size then foo.c must include foo.h.

I) Indentation

I1

Indentation is 4 spaces. Tabs are 8 spaces.

I2

Curly braces are on separate lines indented the same as the statement that precedes them.

I3

Statements inside curly braces are indented one level.

V) Variables

V1

Variables are lower case words separated by underscores (this_is_a_var)

V2

Constants are upper case words separated by underscores. (THIS_IS_A_CONST)

V3

No int declarations. (Use uint8, int8, uint16, int16, uint32, int32 instead.)

V4

One declaration per line. (Exception: Highly coupled variables, i.e. width and height.)

V5

All declarations have a comment after them explaining the variable.

V6

Units are declared when appropriate.

V7

No hidden variables. That is, a variable defined in an inner block may not have the same name as variable in an outer block.

V8

Never use "O" (Capital O) or "l" (lower case "l") for variable or constant names.

S) Statements

S1

No side effects. The operators ++ and -- must be on lines by themselves.

S2

The assignment operator (=) is not used inside an if or other statements.

S3

All switch statements have a default case. (Even if it is /* Do nothing */.)

S4

All switch statement case blocks end in break.

S5

Empty statements must contain continue or /* Do nothing */

R) Preprocessor

R1

The backslashes (\) for a multi-line #define are in the same column.

R2

Use typedef instead of #define. to define new types

R3

Use const instead of #define to define constants.

R4

Put parenthesis around all parameters used in a parameterized macro definition.

R5

#define should never be used to redefine C or C++ keywords. Specifically, it they keyword extern should never be redefined.

M) Memory

M1

All malloc and relelated calls have their return value checked against NULL.

M2

Every malloc has a corresponding free. Every new has a corresponding delete.

M3

Every malloc has a comment explaining where the free is done. the same rule applys for new and delete.

M4

Byte streams should have their length checked to prevent overruns. (Example: use strncpy instead of strcpy)

M5

Every procedure that allocates memory which the caller must free, must document this fact in the function header.

M6

Every memcpy function code should be of the form:
     memcopy(ptr, source, sizeof(*ptr));
whenever possible. Specifically, the third parameter should be sizeof the data pointed to by the first parameter.
A similar rule should be followed for memset.