For the C++ coding standards click here

Contents

1. Names
   • (important recommendations below)
   • Include Units in Names
   • Structure Names
   • C File Extensions
   • (other suggestions below)
   • Make Names Fit
   • Variable Names on the Stack
   • Pointer Variables
   • Global Constants
   • Enum Names
   • #define and Macro Names
2. Formatting
   • (important recommendations below)
   • Brace {} Policy
   • Parens () with Key Words and Functions Policy
   • A Line Should Not Exceed 78 Characters
   • If Then Else Formatting
   • switch Formatting
   • Use of goto,continue,break and ?:
   • (other suggestions below)
   • One Statement Per Line
3. Documentation
   • (important recommendations below)
   • Comments Should Tell a Story
   • Document Decisions
   • Use Headers
   • Make Gotchas Explicit
   • Commenting function declarations
   • (other suggestions below)
   • Include Statement Documentation
4. Complexity Management
   • Layering
5. Miscellaneous
   • (important recommendations below)
   • Use Header File Guards
   • Mixing C and C++
   • (other suggestions below)
   • Initialize all Variables
   • Be Const Correct
   • Short Functions
   • No Magic Numbers
   • Error Return Check Policy
   • To Use Enums or Not to Use Enums
   • Macros
   • Do Not Default If Test to Non-Zero
   • Usually Avoid Embedded Assignments
   • Commenting Out Large Code Blocks
   • Use #if Not #ifdef
   • Miscellaneous
   • No Data Definitions in Header Files

Names

Make Names Fit

A name is the result of a long deep thought process about the ecology it lives in. Only a programmer who understands the system as a whole can create a name that "fits" with the system. If the name is appropriate everything fits together naturally, relationships are clear, meaning is derivable, and reasoning from common human expectations works as expected.

If you find all your names could be Thing and DoIt then you should probably revisit your design.

Function Names

• Usually every function performs an action, so the name should make clear what it does: check_for_errors() instead of error_check(), dump_data_to_file() instead of data_file(). This will also make functions and data objects more distinguishable.

  Structs are often nouns. By making function names verbs and following other naming conventions programs can be read more naturally.

• Suffixes are sometimes useful:
  • max - to mean the maximum value something can have.
  • cnt - the current count of a running count variable.
  • key - key value.

  For example: retry_max to mean the maximum number of retries, retry_cnt to mean the current retry count.

• Prefixes are sometimes useful:
  • is - to ask a question about something. Whenever someone sees Is they will know it's a question.
  • get - get a value.
  • set - set a value.

  For example: is_hit_retry_limit.

Include Units in Names

uint32 timeout_msecs;
uint32 my_weight_lbs;

Structure Names

• Use underbars ('_') to separate name components
• When declaring variables in structures, declare them organized by use in a manner to attempt to minimize memory wastage because of compiler alignment issues, then by size, and then by alphabetical order. E.g, don't use ``int a; char *b; int c; char *d''; use ``int a; int b; char *c; char *d''. Each variable gets its own type and line, although an exception can be made when declaring bitfields (to clarify that it's part of the one bitfield). Note that the use of bitfields in general is discouraged. Major structures should be declared at the top of the file in which they are used, or in separate header files, if they are used in multiple source files. Use of the structures should be by separate declarations and should be "extern" if they are declared in a header file. It may be useful to use a meaningful prefix for each member name. E.g, for ``struct softc'' the prefix could be ``sc_''.

Example

   
struct foo {
	struct foo *next;	/* List of active foo */
	struct mumble amumble;	/* Comment for mumble */
	int bar;
	unsigned int baz:1,	/* Bitfield; line up entries if desired */
		     fuz:5,
		     zap:2;
	uint8_t flag;
};
struct foo *foohead;		/* Head of global foo list */

Variable Names on the Stack

• use all lower case letters
• use '_' as the word separator.

Justification

• With this approach the scope of the variable is clear in the code.
• Now all variables look different and are identifiable in the code.

Example

   
   int handle_error (int error_number) {
      int            error= OsErr();
      Time           time_of_error;
      ErrorProcessor error_processor;
   }

Pointer Variables

• place the * close to the variable name not pointer type

Example

  char *name= NULL;

  char *name, address; 

Global Variables

• Global variables should be prepended with a 'g_'.
• Global variables should be avoided whenever possible.

Justification

• It's important to know the scope of a variable.

Example

    Logger  g_log;
    Logger* g_plog;

Global Constants

• Global constants should be all caps with '_' separators.

Justification

Example

    const int A_GLOBAL_CONSTANT= 5;

#define and Macro Names

• Put #defines and macros in all upper using '_' separators. Macros are capitalized, parenthesized, and should avoid side-effects. Spacing before and after the macro name may be any whitespace, though use of TABs should be consistent through a file. If they are an inline expansion of a function, the function is defined all in lowercase, the macro has the same name all in uppercase. If the macro is an expression, wrap the expression in parenthesis. If the macro is more than a single statement, use ``do { ... } while (0)'', so that a trailing semicolon works. Right-justify the backslashes; it makes it easier to read.

Justification

Some subtle errors can occur when macro names and enum labels use the same name.

Example

#define MAX(a,b) blah
#define IS_ERR(err) blah
#define	MACRO(v, w, x, y)						\
do {									\
	v = (x) + (y);							\
	w = (y) + 2;							\
} while (0)

Enum Names

Labels All Upper Case with '_' Word Separators

Example

   enum PinStateType {
      PIN_OFF,
      PIN_ON
   };

Make a Label for an Error State

Example

enum { STATE_ERR,  STATE_OPEN, STATE_RUNNING, STATE_DYING};

Formatting

Brace Placement

   if (condition) {      while (condition) {
      ...                   ...
   }                     }

When Braces are Needed

Always Uses Braces Form

if (1 == somevalue) {
   somevalue = 2;
}

Justification

One Line Form

if (1 == somevalue) somevalue = 2;

Justification

Add Comments to Closing Braces

while(1) {
   if (valid) {
  
   } /* if valid */
   else {
   } /* not valid */

} /* end forever */

Consider Screen Size Limits

Parens () with Key Words and Functions Policy

• Do not put parens next to keywords. Put a space between.
• Do put parens next to function names.
• Do not use parens in return statements when it's not necessary.

Justification

• Keywords are not functions. By putting parens next to keywords keywords and function names are made to look alike.

Example

    if (condition) {
    }

    while (condition) {
    }

    strcpy(s, s1);

    return 1;

A Line Should Not Exceed 78 Characters

• Lines should not exceed 78 characters.

Justification

• Even though with big monitors we stretch windows wide our printers can only print so wide. And we still need to print code.
• The wider the window the fewer windows we can have on a screen. More windows is better than wider windows.
• We even view and print diff output correctly on all terminals and printers.

If Then Else Formatting

Layout

   if (condition) {
   } else if (condition) {
   } else {
   }

Condition Format

if ( 6 == errorNum ) ...

One reason is that if you leave out one of the = signs, the compiler will find the error for you. A second reason is that it puts the value you are looking for right up front where you can find it instead of buried at the end of your expression. It takes a little time to get used to this format, but then it really gets useful.

switch Formatting

• Falling through a case statement into the next case statement shall be permitted as long as a comment is included.
• The default case should always be present and trigger an error if it should not be reached, yet is reached.
• If you need to create variables put all the code in a block.

Example

   switch (...)
   {
      case 1:
         ...
      /* comments */

      case 2:
      {        
         int v;
         ...
      }
      break;

      default:
   }

Use of goto,continue,break and ?:

Goto

   for (...) {
      while (...) {
      ...
         if (disaster) {
            goto error;

         } 
      }
   }
   ...
error:
   clean up the mess 

When a goto is necessary the accompanying label should be alone on a line and to the left of the code that follows. The goto should be commented (possibly in the block header) as to its utility and purpose.

Continue and Break

Continue and break like goto should be used sparingly as they are magic in code. With a simple spell the reader is beamed to god knows where for some usually undocumented reason.

The two main problems with continue are:

• It may bypass the test condition
• It may bypass the increment/decrement expression

Consider the following example where both problems occur:

while (TRUE) {
   ...
   /* A lot of code */
   ...
   if (/* some condition */) {
      continue;
   }
   ...
   /* A lot of code */
   ...
   if ( i++ > STOP_VALUE) break;
}

From the above example, a further rule may be given: Mixing continue with break in the same loop is a sure way to disaster.

?:

• Put the condition in parens so as to set it off from other code
• If possible, the actions for the test should be simple functions.
• Put the action for the then and else statement on a separate line unless it can be clearly put on one line.

Example

   (condition) ? funct1() : func2();

   or

   (condition)
      ? long statement
      : another long statement;

One Statement Per Line

The reasons are:

1. The code is easier to read. Use some white space too. Nothing better than to read code that is one line after another with no white space or comments.

One Variable Per Line

Not:
char **a, *x;

Do:
char **a = 0;  /* add doc */
char  *x = 0;  /* add doc */

1. Documentation can be added for the variable on the line.
2. It's clear that the variables are initialized.
3. Declarations are clear which reduces the probablity of declaring a pointer when you meant to declare just a char.

To Use Enums or Not to Use Enums

In general enums are preferred to #define as enums are understood by the debugger.

Be aware enums are not of a guaranteed size. So if you have a type that can take a known range of values and it is transported in a message you can't use an enum as the type. Use the correct integer size and use constants or #define. Casting between integers and enums is very error prone as you could cast a value not in the enum.

Use Header File Guards

#ifndef sys_socket_h
  #define sys_socket_h  /* NOT _sys_socket_h_ */
  #endif 
  

Macros

Don't Turn C into Pascal

Replace Macros with Inline Functions

Example

#define  MAX(x,y)	(((x) > (y) ? (x) : (y))	// Get the maximum

The macro above can be replaced for integers with the following inline function with no loss of efficiency:

   inline int 
   max(int x, int y) {
      return (x > y ? x : y);
   }

Be Careful of Side Effects

Example

   MAX(f(x),z++);

Always Wrap the Expression in Parenthesis

Example

#define ADD(x,y) x + y

must be written as 

#define ADD(x,y) ((x) + (y))

Make Macro Names Unique

1. Prepend macro names with package names.
2. Avoid simple and common names like MAX and MIN.

Initialize all Variables

• You shall always initialize variables. Always. Every time. gcc with the flag -W may catch operations on uninitialized variables, but it may also not.

Justification

• More problems than you can believe are eventually traced back to a pointer or variable left uninitialized.

Short Functions

• Functions should limit themselves to a single page of code.

Justification

• The idea is that the each method represents a technique for achieving a single objective.
• Most arguments of inefficiency turn out to be false in the long run.
• True function calls are slower than not, but there needs to a thought out decision (see premature optimization).

Document Null Statements

   while (*dest++ = *src++) 

  {
      ;       

   }  

Do Not Default If Test to Non-Zero

   if (FAIL != f()) 

   if (f()) 

   #define STREQ(a, b) (strcmp((a), (b)) == 0) 

Or better yet use an inline method:

   inline bool
   string_equal(char* a, char* b)
   {
      (strcmp(a, b) == 0) ? return true : return false;
	  Or more compactly:
      return (strcmp(a, b) == 0);
   }

Note, this is just an example, you should really use the standard library string type for doing the comparison.

The non-zero test is often defaulted for predicates and other functions or expressions which meet the following restrictions:

• Returns 0 for false, nothing else.
• Is named so that the meaning of (say) a true return is absolutely obvious. Call a predicate is_valid(), not check_valid().

Usually Avoid Embedded Assignments

   while (EOF != (c = getchar())) {
      process the character
   }

The ++ and -- operators count as assignment statements. So, for many purposes, do functions with side effects. Using embedded assignment statements to improve run-time performance is also possible. However, one should consider the tradeoff between increased speed and decreased maintainability that results when embedded assignments are used in artificial places. For example,

   a = b + c;
   d = a + r; 

   d = (a = b + c) + r; 

Documentation

Comments Should Tell a Story

Document Decisions

Use Headers

These headers are structured in such a way as they can be parsed and extracted. They are not useless like normal headers. So take time to fill them out. If you do it right once no more documentation may be necessary.

Comment Layout

Make Gotchas Explicit

Gotcha Keywords

• @author:
  specifies the author of the module

• @version:
  specifies the version of the module

• @param:
  specifies a parameter into a function

• @return:
  specifies what a function returns

• @deprecated:
  says that a function is not to be used anymore

• @see:
  creates a link in the documentation to the file/function/variable to consult to get a better understanding on what the current block of code does.
• @todo:
  what remains to be done

• @bug:
  report a bug found in the piece of code

Gotcha Formatting

• Make the gotcha keyword the first symbol in the comment.
• Comments may consist of multiple lines, but the first line should be a self-containing, meaningful summary.
• The writer's name and the date of the remark should be part of the comment. This information is in the source repository, but it can take a quite a while to find out when and by whom it was added. Often gotchas stick around longer than they should. Embedding date information allows other programmer to make this decision. Embedding who information lets us know who to ask.

Commenting function declarations

Include Statement Documentation

Layering

A layering violation simply means we have dependency between layers that is not controlled by a well defined interface. When one of the layers changes code could break. We don't want code to break so we want layers to work only with other adjacent layers.

Sometimes we need to jump layers for performance reasons. This is fine, but we should know we are doing it and document appropriately.

Miscellaneous

General advice

• Don't use floating-point variables where discrete values are needed. Using a float for a loop counter is a great way to shoot yourself in the foot. Always test floating-point numbers as <= or >=, never use an exact comparison (== or !=).

• Compilers have bugs. Common trouble spots include structure assignment and bit fields. You cannot generally predict which bugs a compiler has. You could write a program that avoids all constructs that are known broken on all compilers. You won't be able to write anything useful, you might still encounter bugs, and the compiler might get fixed in the meanwhile. Thus, you should write ``around'' compiler bugs only when you are forced to use a particular buggy compiler.

• Do not rely on automatic beautifiers. The main person who benefits from good program style is the programmer him/herself, and especially in the early design of handwritten algorithms or pseudo-code. Automatic beautifiers can only be applied to complete, syntactically correct programs and hence are not available when the need for attention to white space and indentation is greatest. Programmers can do a better job of making clear the complete visual layout of a function or file, with the normal attention to detail of a careful programmer (in other words, some of the visual layout is dictated by intent rather than syntax and beautifiers cannot read minds). Sloppy programmers should learn to be careful programmers instead of relying on a beautifier to make their code readable. Finally, since beautifiers are non-trivial programs that must parse the source, a sophisticated beautifier is not worth the benefits gained by such a program. Beautifiers are best for gross formatting of machine-generated code.

• Accidental omission of the second ``='' of the logical compare is a problem. The following is confusing and prone to error.

          if (abool= bbool) { ... }
       

  Does the programmer really mean assignment here? Often yes, but usually no. The solution is to just not do it, an inverse Nike philosophy. Instead use explicit tests and avoid assignment with an implicit test. The recommended form is to do the assignment before doing the test:

  
         abool= bbool;
         if (abool) { ... }
      

• Modern compilers will put variables in registers automatically. Use the register sparingly to indicate the variables that you think are most critical. In extreme cases, mark the 2-4 most critical values as register and mark the rest as REGISTER. The latter can be #defined to register on those machines with many registers.

Be Const Correct

Use #if Not #ifdef

#ifdef DEBUG
        temporary_debugger_break();
#endif

cc -c lurker.cc -DDEBUG=0

#if DEBUG
        temporary_debugger_break();
#endif

#if !defined(USER_NAME)
 #define USER_NAME "john smith"
#endif

Commenting Out Large Code Blocks

Using #if 0

   void 
   example()
   {
      great looking code

      #if 0
      lots of code
      #endif
    
      more code
    }

You can't use /**/ style comments because comments can't contain comments and surely a large block of your code will contain a comment, won't it?

Don't use #ifdef as someone can unknowingly trigger ifdefs from the compiler command line. #if 0is that even day later you or anyone else has know idea why this code is commented out. Is it because a feature has been dropped? Is it because it was buggy? It didn't compile? Can it be added back? It's a mystery.

Use Descriptive Macro Names Instead of #if 0

#if NOT_YET_IMPLEMENTED  

#if OBSOLETE

#if TEMP_DISABLED 

Add a Comment to Document Why

No Data Definitions in Header Files

/* 
 * aheader.h 
 */
int x = 0;

1. It's bad magic to have space consuming code silently inserted through the innocent use of header files.
2. It's not common practice to define variables in the header file so it will not occur to developers to look for this when there are problems.
3. Consider defining the variable once in a .c file and use an extern statement to reference it.

Mixing C and C++

Calling C Functions from C++

extern "C" int strncpy(...);
extern "C" int my_great_function();
extern "C"
{
   int strncpy(...);
   int my_great_function();
};

Creating a C Function in C++

extern "C" void
a_c_function_in_cplusplus(int a)
{
}

__cplusplus Preprocessor Directive

#ifdef __cplusplus

extern "C" some_function();

#else

extern some_function();

#endif

No Magic Numbers

if      (22 == foo) { start_thermo_nuclear_war(); }
else if (19 == foo) { refund_lotso_money(); }
else if (16 == foo) { infinite_loop(); }
else                { cry_cause_im_lost(); }

#define   PRESIDENT_WENT_CRAZY  (22)
const int WE_GOOFED= 19;
enum  {
   THEY_DIDNT_PAY= 16
};

if      (PRESIDENT_WENT_CRAZY == foo) { start_thermo_nuclear_war(); }
else if (WE_GOOFED            == foo) { refund_lotso_money(); }
else if (THEY_DIDNT_PAY       == foo) { infinite_loop(); }
else                                  { happy_days_i_know_why_im_here(); }