TinyMUX Coding Guidelines

From TinyMUX

Contents 1 Introduction 2 Names 3 Tabs 4 Indention 5 Spacing 6 Comments 7 NULL 8 Subset the Language

Introduction

No coding style is perfect in purpose or perfectly internally consistent. Also, many style choices are necessarily arbitrary -- that is, there may be no compelling benefit for picking one element of style over another even if there is a benefit for consistently applying a style.

Names

Avoid short, cryptic names. Longer names are generally better than shorter ones. Names should be spelled correctly. Names should allude to their higher-level semantics of the problem domain instead of their lower-level language type.

Tabs

No hardtabs. Spaces only. No spaces left at the end of the line.

Indention

Four spaces per indention level.

TinyMUX uses the Allman style of bracing. The tools are there to easily find matching braces, but is still visually helpful if matching parenthesis, square brackets, and curly braces occur either in the same row or the same column.

if (x == y)
{
    p++;
}

The curly braces are at the same indention level as if control keyword (if, while, switch). The contained block representing a new scope is indented one level. For structures and unions,

typedef struct NODE
{
    int foo;
} NODE;

NODE Nodes[2] =
{
    1, 2
};

For switch, the case keywords should be at the same indention level as the switch keyword. Always use the break keyword. A blank line should separate each case.

switch (ch)
{
case 'a':
case 'A';
    x = ch;
    break;

default:
    y = ch;
    break;
}

While not required, deeply-nested boolean expressions can be expressed in the following style:

if (  a == b
   && (  c < d
      || d < e + 1
      || p == q))
{
    ..
}

The && and || operators appear under their corresponding opening parenthesis. Notice this breaks spacing, indention, and matching rules described elsewhere. However, one can easily check that && and || always alternate (otherwise, unnecessary parenthesis have been used), and each clause is lined up and appears in the order it will be evaluated. This form also makes it easier to perform DeMorgan transforms with the ! operator.

For less complex boolean expressions, this degree of styling is not necessary.

Spacing

Use a single space after each comma between function arguments. Do not use spaces between the parenthesis and function arguments. Do not use spaces between the function name and the leading parenthesis. Do no use spaces inside square brackets. Do use a space after control flow keywords. Do use a space before and after comparison operators.

while (x == Foo(a, b, ch))
{
    ch = str[x];
}

Comments

Doxygenated comment blocks should be expressed with /* */. Otherwise, either syntax (// or /* */) may be used for comments.

Comments should not simply restate the plain meaning of source code in psuedo-English. They need to reveal information not easily revealed from a plain reading the code itself. Comments should use proper grammer and punctuation.

Also, while either syntax (// or /* */) can be used for comments, there is still the question of how many lines of code should be covered by a comment: one line or several adjacent ones. The former, we will call line-oriented; the latter, block-oriented.

Line-oriented comments appear in the legacy portions near some global variable definitions, but generally, it is very difficult to reveal anything high-level about a single line of code that isn't already obvious.

Instead, a block-oriented style is preferred.

    // We look for the lost puppy in all of the locations we know about.  Finding
    // the puppy this way is relatively expensive.
    //
    bool bFound = false;
    for (int i = 0; i < N; i++)
    {
        if (IsPuppyHere(i))
        {
            bFound = true;
            break;
        }
    }

NULL

When using NULL to indicate whether or not a variable has been initialized, explicitly use NULL in the comparison. Do not leave pointers uninitialized or left to point at random memory:

if (NULL != p)
{
    FooRemoveBlock(p);
    p = NULL;
}

Subset the Language

To avoid being one typo away from assigning a constant to a variable instead of comparing against it, use constants as lvalues where possible:

if (NULL == p)
{
    ...
}

Don't use the greater-than and greater-than-or-equal (> and >=) comparisons:

if (  minimum <= x
   && x <= maximum)
{
   ...
}

Don't use pre-increment and pre-decrement. Avoid using post-increment and post-decrement except by themselves:

p++;
q--;

Just because a language allows something does not mean that it is good practice to use it.