C Coding Standard for GOLD

This is a work in progress, some changes may be made. Also, not all code curretly follows this standard, but all new code does.

Entity Naming

Names

Indentation and Spacing

Comments

Files

Declarations

Statements

Other Typographical Issues

Entity Naming

Variables shall begin with a lower case letter and words shall begin with an upper case letter.

Constants shall begin with an upper case letter.

Functions shall begin with an upper case letter and words shall begin with an upper case letter.

Types shall begin with an upper case letter and words shall begin with an upper case letter.

Enumerators shall begin with an upper case letter and words shall begin with an upper case letter.

Macros shall be upper case and words shall be separated by underscore (_).

Names

Use sensible, descriptive names.

Do not use short cryptic names or names based on internal jokes. It shall be easy to type a name without looking up how it is spelt.

Exception: Loop variables and variables with a small scope (less than 20 lines) may have short names to save space if the purpose of that variable is obvious.

Only use english names.

It is confusing when mixing languages for names. English is the preferred language because of its spread in the software market and because most libraries used already use english.

Variables with a large scope shall have long names, variables with a small scope can have short names.

Scratch variables used for temporary storage or indices are best kept short. A programmer reading such variables shall be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.

Indentation and Spacing

Braces shall follow "BSD Style".

The BSD Bracing Style means that the curly brace pair are lined up with the surrounding statement. Statements and declarations between the braces are indented relative to the braces.

Braces shall be indented 4 columns to the right of the starting position of the enclosing statement or declaration.

Example: 
void F(int a)
{
    int i;
    if (a > 0)
    {
        i = a;
    }
    else
    {
        i = a;
    }
}

Loop and conditional statements shall always have brace enclosed sub-statements.

The code looks more consistent if all conditional and loop statements have braces.

Even if there is only a single statement after the condition or loop statement today, there might be a need for more code in the future.

Each statement shall be placed on a line on its own.

There is no need to make code compact. Putting several statements on the same line only makes the code cryptic to read.

Declare each variable in a separate declaration.

This makes it easier to see all variables. It also avoids the problem of knowing which variables are pointers. 
int* p, i;
It is easy to forget that the star belongs to the declared name, not the type, and look at this and say that the type is "pointer to int" and both p and i are declared to this type.

All binary arithmetic, bitwise and assignment operators and the ternary conditional operator (?:) shall be surrounded by spaces; the comma operator shall be followed by a space but not preceded; all other operators shall not be used with spaces.

Lines shall not exceed 78 characters.

Even if your editor handles long lines, other people may have set up their editors differently. Long lines in the code may also cause problems for other programs and printers.

Comments

Comments shall be written in english

Use JavaDoc style comments.

The comment styles /// and /** ... */ are used by JavaDoc, Doxygen and some other code documenting tools.

All comments shall be placed above the line the comment describes, indented identically.

Being consistent on placement of comments removes any question on what the comment refers to.

Use #ifdef instead of /* ... */ to comment out blocks of code.

The code that is commented out may already contain comments which then terminate the block comment and causes lots of compile errors or other harder to find errors.

Every function shall have a comment that describes its purpose.

Files

There shall only be one externally visible function defined in each header file.

Having as few declarations as possible in a header file reduces header dependencies.

The header file shall have the same name as the function plus extension h.

File name shall be treated as case sensitive.

C source files shall have extension ".c".

Objective-C source files shall have extension ".m".

C header files shall have extension ".h".

C Header files must have include guards.

The include guard protects against the header file being included multiple times.

Example: 

#ifndef FILE_H
#define FILE_H
...
#endif
This pertains only to C headers. Objective-C headers use #import, not #include.

The name of the macro used in the include guard shall have the same name as the file (excluding the extension) followed by the suffix "_H".

Header files shall be self-contained

When a header is included, there shall not be a need to include any other headers first.

A simple way to make sure that a header file does not have any dependencies is to include it first in the corresponding source file. Example: 

/* foobar.h */

#include "foobar.h"
#include <stdio.h>

...

System header files shall be included with <> and project headers with "".

Put #include directives at the top of files.

Having all #include directives in one place makes it easy to find them.

Do not use absolute directory names in #include directives.

The directory structure may be different on other systems.

Do not use relative directory names in #include directives.

The directory structure of the project may change in the future. It is then difficult to correct all the directory names.

Each file must start with a copyright notice.

Declarations

Provide names of parameters in function declarations.

Parameter names are useful to document what the parameter is used for.

The parameter names shall be the same in all declarations and definitions of the function.

Always provide the return type explicitly.

Use a typedef to define a pointer to a function.

Pointers to functions have a strange syntax. The code becomes much clearer if you use a typedef for the pointer to function type. This typedef name can then be used to declare variables etc. 
double Sin(double arg);
typedef double (*TrigFunc)(double arg);

/* Usage examples */
TrigFunc myFunc = Sin;
void CallFunc(TrigFunc callback);
TrigFunc funcTable[10];

Do not use global variables.

Global variables are initialised when the program starts whether it will be used or not. Sometimes global variables are necessary, but their use is strongly discouraged.

If global variables are using other global variables for their initialisation there may be a problem if the dependent variables are not initialised yet. The initialisation order of global variables in different object files is not defined.

Statements

Only use gotos for error recovery.

Although gotos are considered bad and breaks structured coding, it is sometimes useful for error recovery from deep within nested loops. In these cases the goto shall only jump to a label below in the code and only into an outer scope.

All switch statements shall have a default label.

Even if there is no action for the default label, it shall be included to show that the programmer has considered values not covered by case labels. If the case labels cover all possibilities, it is useful to put an assertion there to document the fact that it is impossible to get here. An assertion also protects from a future situation where a new possibility is introduced by mistake.

Other Typographical Issues

Avoid macros.

Most macros can be replaced by constants, enumerations or inline functions.

As macros are not part of the C++ language, they do not provide type safety and debugger support.

Do not use literal numbers other than 0 and 1.

Use constants instead of literal numbers to make the code consistent and easy to maintain. The name of the constant is also used to document the purpose of the number.

Do not rely on implicit conversion to bool in conditions.

if (ptr)         // wrong
if (ptr != NULL) // ok