Back to main

Good Programming Style

Curly braces

Use them. All the time. Even if not strictly necessary.

Bad:

if (x==1)
    printf("x is one.\n");

Good:

if (x==1) {
    printf("x is one.\n");
}

Indentation

As long as you follow the rule about curly braces, indentation is trivial:

  1. Begin at the left-hand side.
  2. For each a opening {, add one level of indentation.
  3. For each closing }, remove one level of indentation.

A "level of indentation" could be one tab, 8 spaces, 4 spaces, or 2 spaces (consistently throughout the whole file).

Bad:

int main() {
  int i, x;
for (i=0; i<10; i++)
     {
     if (i==3)
{
            x = 39;       }
}}

Good:

int main() {
    int i, x;
    for (i=0; i<10; i++) {
        if (i==3) {
            x = 39;
        }
    }
}

Also good:

int main()
{
    int i, x;
    for (i=0; i<10; i++)
    {
        if (i==3)
        {
            x = 39;
        }
    }
}

Also good: (default emacs style, not used elsewhere)

int main()
{
    int i, x;
    for (i=0; i<10; i++)
      {
        if (i==3)
          {
            x = 39;
          }
      }
}

Line length

Avoid having statements so long that the lines "wrap around". A good rule of thumb is to not exceed 80 characters on each line.

When writing printf statements, this might mean that you need to split the desired output into two (or more) separate printf statements.

If a function is too long for one line, you can continue it on the next line, but the second line should be indented somewhat.

Bad:

if (x==1) {
    if (y==1) {
        z = calcStuff(x, y, "a bunch of text",
abc, aVariableWithALongName, anotherVariable);
    }
}

Good:

if (x==1) {
    if (y==1) {
        z = calcStuff(x, y,
                      "a bunch of text", abc,
                      aVariableWithALongName,
                      anotherVariable);
    }
}

Variable and Function names

The computer doesn't care what names you use, but choosing good names can make your code a lot easier to read and write -- as well as eliminating the need for comments. For example, what does this code do?

x = x * 1.609344;

Well, obviously it multiplies x by a constant value... but why are we doing that? Adding a comment would help, but the code would be even more clear if changed the variable name:

// converts from miles to km.
distance = distance * 1.609344;

However, this still isn't perfect. What if we accidently wrote this line twice, in different parts of our code? What if we wanted to convert from km to miles instead? This is much more clear, and we don't need any comment:

distance_km = distance_miles * 1.609344;

A similar thing applies to functions. What does this function do? You might need to think about it for a bit:

float f(float one, float two) {
    return sqrt(one*on + two*two);
}

Here's the same function, with better names:

float hypotenuse(float a, float b) {
    return sqrt(a*a + b*b);
}

Comments

Learning how to write good comments is like learning how to write good poetry: textbooks and lectures won't help much. The only real way to learn is to read other people's code+comments, write your own code+comments, go away for a year, then read the stuff you wrote and wince.

I've spent hours trying to figure out code I wrote six months ago, cursing myself all the while. It's really fun (not!) when you can't figure out how your own program works. It seemed so obvious at the time, but after a few months... :(


That said, you don't have the luxury of waiting a year before re-reading your code. So here's a few comment guidelines:


Creative Commons LicenseUnless otherwise noted, all materials on these pages are licenced under a Creative Commons Licence.