Coding Style and Guidelines

The purpose of a coding style and accompanying guidelines is to make the reading and comprehension of the code easier. Reading prose would also be much harder, should the punctuation rules differ from chapter and paragraph to the next.

NOTE As long as this line is here, this is not approved and still under work.

Coding Style

In general, these must be followed.

Consistency

• Be consistent.

  In a particular context, everything should style wise look the same.

• In Rome do as the romans do.

  If something is done in a particular way in some context, then follow that same way when doing modifications.

General

• Only spaces, no tabs.
• Indentation depth 4 spaces.
• No trailing white space.
• Maximum line length 110 characters.

Indentation Style

• Allman

  The brace associated with a control statement is placed on the next line, indented to the same level as the control statement. Statements within the braces are indented to the next level.

    if (something)
    {
       do_this();
    }
    else
    {
        do_that();
    } 
  

Punctuation

• Keywords are followed by a space.

    if (something)
       ...;
  
    while (something)
       ...;
  

• Function name and opening parenthesis are not separated by a space.

    someFunction();
  

• Binary operators are always surrounded by spaces.

    if (a != b)
       ...;
  
    x = a + b + c / d;
  
    x = a ? b : c;
  

• Comma is always followed by a space.

    x = someFunction(a, b, c + d);
  

• Opening parenthesis and square bracket are not followed by a space, and closing parenthesis and square bracket are not preceded by a space.

    int len = strlen(name);        
  
    a = b[5];
  

Guidelines

In general, these should be followed unless there is a good reason not to.

• Try to have only a single exit-point in each function.

  Rationale: With multiple exit points it is very easy to overlook the release of some resource in one of those places.

  Reasonable exceptions to the single exit point rule are:

  • Checking of preconditions at the beginning of the function.

       int function(int a, int b)
       {
           if (a < 0)
               return -1;
       
           if (b > 5)
               return -1;
       
           int rv;
           ...
           return rv;
       }
    

  • Functions that are basically only big switches.

       char* toString(enum Color c)
       {
           switch (c)
           {
               case RED:
                   return "RED";
        
               case GREEN:
                   return "GREEN";
        
               default:
                   return "Unknown";
           }
       }
    

• Try to keep the line length less than 80 characters.

  Rationale: In typography the optimal line length for readability is considered to be around 60 characters. With 5 levels of nesting of 4 spaces each, that gives 80 characters. If it is hard to stay within that limit, consider refactoring the function.

• Use parenthesis to make the precedence explicit, even if precedence rules would not require it.

    if (a != b && !ready()) ...;
  
    if ((a != b) && !ready()) ...;
  

  Rationale: There can never be any doubt about what the intended precedence is.

• Try to keep the length of each function less than what fits in one screen full (roughly 60 lines).

  Rationale: That way it is possible with one glance to get a grasp of what the function does. If it's hard to keep within the limit it may be a sign that the function ought to be refactored.

• Use vertical space (i.e. empty lines) to introduce paragraphs and sections.

  Rationale: Makes the reading easier.