Variable Names

Choose meaningful names for variables, constants and functions. Names are the heart of programming. In the past people believed knowing someone’s true name gave them magical power over that person. If you can think up the true name for something, you give yourself and the people coming after power over the code. Don’t laugh!

A name is the result of a long deep thought process about the ecology it lives in. Only a programmer who understands the system as a whole can create a name that “fits” with the system. If the name is appropriate everything fits together naturally, relationships are clear, meaning is derivable, and reasoning from common human expectations works as expected.

Good

weekly_pay = hours_worked * hourly_pay_rate;

Bad

a = b * c;


Function Names

Usually every function performs an action, so the name should make clear what it does.

Suffixes are sometimes useful:

  • max – to mean the maximum value something can have.
  • cnt – the current count of a running count variable.
  • key – key value.

Prefixes are sometimes useful:

  • is – to ask a question about something. Whenever someone sees is they will know it’s a question.
  • get – get a value.
  • set – set a value.

Good

bool is_even(unsigned int i) {
  if (i % 2 == 0) return true;
}

bool is_odd(unsigned int i) {
  if (i % 2 == 1) return true;
}

Bad

bool helper1(unsigned int i) {
  if (i % 2 == 0) return true;
}

bool helper2(unsigned int i) {
  if (i % 2 == 1) return true;
}


Main Function

The main function should always return a value which determines whether your program has terminated successfully. There are conventions for what sorts of status values certain programs should return. The most common convention is simply 0 for success and 1 for failure.

Good

int main() {
  // perform computation

  if (is_error) {
    // unsuccessful program completion
    return 1;
  }

  // program completed successfully
  return 0;
}


Indentation

Use consistent indentation (typically 2 spaces). If the indenting level is more than 4 or 5 levels you may think about factoring out code.

Good

if (some_check) {
  if (some_other_check) {
    while (more input) {
    }
  }
}

Bad

if (some_check) {
if (some_other_check) {
while (more input) {
}
}
}

Further, to make your code more readable, leave one blank space between operators.

Good

x = a + b * 3;

Bad

x=a+b*3;


Brace Placement

There are two major brace placement strategies that are acceptable:

  1. Place brace under and inline with keywords:

Good

  if (condition)
  {

  }
  1. Place the initial brace on the same line as the keyword and the trailing brace inline on its own line with the keyword:

Good

  if (condition) {

  }

You can choose either of the two strategies shown above. However, you should be consistent in using one strategy and not mix them together.

Bad

    if (condition)
        {

        }

Bad

    if (condition)
{

          }


Brace Usage

All if, while and do while statements must either have braces or be on a single line. It ensures that when someone adds a line of code later there are already braces and they don’t forget. It provides a more consistent look and this doesn’t affect execution speed.

Good

if (condition) {
  return 0;
}

Good

if (condition) ++i;

To illustrate what can go wrong consider an example shown below which does not use braces.

Bad

if (condition)
  ++i;

The code can be later modified by adding more statements in the if condition but forgetting to put the braces.

Bad

if (condition)
  ++j;
  ++i; // misleading. Seems like it's executed when the conditions is true

By mistake, the code is now executing ++i every time, even when the condition is false. This is because the indentation does not any effect on the scope of statements that belong to the if, only braces have. As a result, the above code is equivalent to:

Good

if (condition) {
  ++j;
}
++i;

where it is clear that ++i is executed all the time.


Parentheses

Do not put parentheses next to keywords. Put a space between.

Good

if (condition) {

}

Bad

if(condition) {

}

Keywords are not functions. By putting parentheses next to keywords keywords and function names are made to look alike.

On the other hand, do put parentheses next to function names.

Good

fibonacci(4);

Bad

fibonacci (4);


Operators Clarity

Use parentheses for clarity, especially with boolean operations. If you have to think about what is the operator precedence then it’s likely that it’s unclear other people as well.

Good

if ((a || b) && c) {

}

Bad

if (a || b && c) {

}