Coding Style

In a team programming environment, it is important to adopt a single programming style so that the look and feel of the code seem unified even though multiple people are working on it. It is also easier to do diffs on different versions of the code so that coding style differences won't show up as differences. Most often, the editor in an IDE (Integrated Development Environment) has coding style options. Therefore, if everyone in the team configures the coding style the same way, the editor will take care most of it for you. In the following sections, I will discuss some of the coding style elements and why I prefer one way over the others. Then instructions on how to configure WindRiver to the preferred coding style are also provided.

Elements of Coding Style

Line Length

Generally, you want to keep the line length just long enough to show a decent amount of indented code without the need to scroll the screen horizontally. If the line is becoming too long, you may consider breaking the line into multiple lines (e.g. breaking a long and complex expression into smaller sub-expressions in their own lines or breaking a long function call with one parameter per line). Keeping line length short is also useful if you ever use some older text editors such as vi in a command window that has a fix width of 80 characters per line. Some good line lengths are: 80, 100 or 120. I personally prefer 80 because I use vi a lot. Realistically, 100 is a good compromise. Here are some examples showing how to break up long lines:

    if (((variableA == valueX) ||
         (variableA == valueY)) &&
        (variableA > valueB) &&
        (variableA < valueC))
    {
        // do something here
    }

    value = SomeFunctionXYZ(param1,    // parameter 1
                            param2,    // parameter 2
                            param3);

Indentation

Indentation allows you to visually align blocks of code. It helps you to follow the flow of the code and spot bugs easier. Indentation spacing should be long enough so that you can follow nesting indented code without losing track of the alignment. But it should be short enough so that deeply indented code won't extend your line to unreasonably long length. In general, indentation of 4 spaces are universally accepted as the most common practice. Most of the Integrated Development Environments (IDE) allows you to change the indentation spacing (usually default at 4) and associate the TAB key to indent the line with the indentation spacing. However, most IDEs also allows you to configure if the each indentation should be stored as a TAB character (ASCII code 9) or as four SPACE characters (ASCII code 32) in the source code file. By default, most IDEs store indentations as TAB characters. Unfortunately, if you use other editors or viewers to view the source code, they may have a different interpretation of the TAB characters. Most interpret it as 8-character spacing. The situation becomes worse if the programmer is mixing SPACES with TABs in their indentations. It may look fine in the IDE but it will totally mess up the code alignment in other editors or viewers. Therefore, it is highly recommeded to configure the IDE to store SPACES insteads of TABs as the indentation characters. Please refer to the section below on how to configure WindRiver accordingly.

Spacing

Spacing between different coding elements (i.e. tokens) are also important in helping to spot bugs. Although the C/C++ language allows liberal use of spaces between tokens, appropriate spacing between tokens will enhance code readability. In general, there should be one space between all coding elements. The parenthesis following a function name is considered part of the function name thus should not have a space between them. Here are some recommended spacing examples and also non-recommended spacing examples:

    //
    // Recommended spacing.
    //
    if (expression)
    {
        y = x + 4;
    }
    value = expression;
    value = Calculate(param1, param2, param3);
    switch (expression)
    {
    case 1:
        x = y + 1;
        break;

    case 2:
        fActive = fEnabled && (valueX >= 0) && (valueX <= 10);
        break;
    }
    return x + y;

    //
    // Non-recommended spacing.
    //
    if( ( ( valueX<=4 )||( valueX>=9 ) ) ){
        x=y+4*5/9+z;
    }
    value= Calculate (        param1,
                         param2,param3 );
    return(x+y+z);

Parentheses

When a long and complex expression involves a lot of parenthesis, the expression should be broken down into sub-expressions on multiple lines. Effort should be made to indent the line so that the parenthesis aligns the nesting level of the expression. Here are some examples showing how proper alignments will enhance the readability and hence reduce the possibility of unintended bugs.

    if (fEnable &&
        ((valueX <= 0) || (valueX >= 10)) &&
        (valueY >= 0) && (valueY <= 100))
    {
        result = valueX*valueX + valueY*valueY;
    }

Braces

Braces are used in C/C++ to group a block of statements. One of the popular styles of using braces is to put the opening brace at the end of the statement. Another style is to put the opening and closing braces alone at the beginning of the line. I prefer the latter because it allows me to move and comment out blocks of code without having to deal with the orphaned open or close braces at the previous or the next statement. Here is an example showing the difference:

    //
    // Not recommended.
    //
    if (expression) {
        doA();
#if 0
    } else {
        doB();
    }
#endif

    //
    // Recommended.
    //
    if (expression)
    {
        doA();
    }
#if 0
    else
    {
        doB();
    }
#endif

Code Layout

Naming Conventions

Configuring Coding Style in WindRiver

To configure the coding style in WindRiver, follow the instructions below:

CodingStyle (last edited 2010-09-27 21:21:18 by MikeTsang)