Colored pencilsWhen writing source code, it is important to use consistent styles of formatting and variable names.  We call these “coding standards”.  Use of consistent styles within an organization results in code being more easily maintained and more readily reused.

Everyone accepts that identifiers should be meaningful and blocks of code should be indented, but how these ideals are achieved is hotly debated with a religious fervor.  We will attempt to address two of the most hotly debated and make the case for our preferences.

Curly braces

In C++, C#, and Java, among other languages, curly braces are used to delimit blocks of code.  Some programmers prefer to open blocks with the curly brace at the end of the previous line and others prefer to place it on a new line.

if (a < b) {
CallFunction();
CallAnotherFunction();
}

if (a < b)
{
CallFunction();
CallAnotherFunction();
}

An advantage of the former option is that it allows code to be more compact and not waste a line. This option makes blocks look similar to those in Visual Basic, Fortran, Pascal, or other languages which do not use curly braces.

We, however, prefer the second option – placing the opening brace on the following line – not so much because of any readability advantage, but because it makes it much less likely to accidentally forget to add curly braces. By always adding curly braces (even when there is only one statement inside the block) and always placing them on the next line, they are most conspicuous if absent.

Variable naming standards

Hungarian notation is probably the most commonly used formal convention for variable naming and was highly recommended by Microsoft in 1999.  Even in 2004, they published a long list of prefixes, but Microsoft has apparently reversed itself and now says not to use it.  In Hungarian notation, variables are named first with one prefix indicating the variable’s scope, with another indicating its type, and then a meaningful name.  So a member of a class of type integer that is used for tracking the number of widgets might be name m_intWidgetCount.

Of course, this can lead to some confusing names (a pointer to a null-terminated string might be prefixed with “m_lpsz”).  Another disadvantage is that it makes the “IntelliSense” feature potentially less useful – if everything starts with m_, int, or str, it’s much harder to find what you are looking for.

Our general standard has been to use Hungarian for internal member variables in source code, but not for public property names or for names of database objects. For portions of your work that are potentially exposed to developers outside of your organization or business unit – public properties, database objects – the advantage of readability and the ability to use IntelliSense outweighs the advantage of variable names telling you their types.

Whatever standards your organization uses, it is important that they be documented and used consistently.  Consistent coding standards help to encourage positive programming habits, increase reuse, and increase maintainability.

What other thoughts do you have on coding naming conventions or policies that your organization has set forth?

image credit: Ivan Prole

3 Comments

  1. Kevin Peck

    It seems there is a toggle switch for each job change. Two jobs back it was { on same line as if, one job back it was { on line by itself, current job it is back up on same line. In the end consistency at the company matters but the global choice does not bother me at all any more other than my home code tends to follow what I am using at work at the given moment.

    I like the { on its own line to visually line things up but I like it with the if to save on code space. Generally the more code I can see the easier it is to debug and spot issues. Since I always use then, even for an if with only one line of code, I don’t worry about missing them.

    Other code formatting issues:

    Always use braces even for single line if? (Yes, please)

    Good old TAB vs SPACE (I like SPACE, have used TAB)

    How far to indent? (4 seems to be most common)

    //TODO comments – how long before you actually do it? I prefer to have them cleaned up at major release time. If they stick around forever made an official feature request to fix the problem.

    Comment out code or delete it? Version control lets you get it back so I delete it as soon as I can.

    ENUM vs static int. Use ENUM if language supports it for stricter compiler checking but you have to watch folks who delete from the middle if you use the ordinal values in a DB.

  2. Jeff Self

    As a fan of Python, coding standards are expected. Python actually has a “rule” called PEP 8 – Style Guide for Python Code. You are expected to follow this guide.

    Guido van Rossum stated that code is read much more often than it is written. Hence, the style guide.

    http://www.python.org/dev/peps/pep-0008/

  3. David T

    Kevin, I used to always use three spaces. It seems to be the minimum for readability and the more you have, the further to the right you deep blocks and if you’re on a laptop, that’s obnoxious. But with the Visual Studio default being hard tabs and a width of four, I have grudgingly given in … otherwise, code looks awful when you copy/paste something from another source.

Comments are closed.