C++ Style Guidelines

by Andrew Morgan

There are tons of style guidelines out there, and everyone's are different. This is a very brief (and incomplete, I'm sure) list of general style guidelines that I try to follow when programming in C++. Not all style guidelines make sense in all situations. There are definitely exceptions to most every style guideline where breakly the general rule makes more sense, makes your program more readable, or results in a direct adherance to the specifications to a project you are working on.

  1. BE CONSISTENT! This is the most important style rule of all, and should never be broken. Once you choose a style, you should stick with it consistently, otherwise it looks like your code was pieced together, and it becomes very difficult to read and/or comprehend.
  2. Claim your code! At the top of EVERY SINGLE program you write, no matter how big or how small, put in a comment containing the programmer's name, the date, and a brief purpose of what the program does.
  3. Comment your code! This is another big one. This business of commenting is often overlooked. Remember that inline comments are not just for other people reading your code, but also for your own clarifications after not having looked at your code in quite a while. Don't overcomment, though.. If you have the line "i = 5;" it isn't necessary to a comment saying "setting i to 5". Once you start programming more and more, this becomes more obvious what does and what does not need commenting.
  4. Choose good identifiers! When you name variables or functions, name them something logical. A program that declares 26 variables, all of different types, etc, and names the variables a, b, c, d, e, ... etc is a very poorly written program. Use your identifiers to help clarify your program. Naming a variable "sumOfGrades" allows a reader to understand that variables purpose, just due to its name. If you had named that variable "a" instead, it would be much more difficult to decipher. Note: the exception to this rule is loop variables. Loop variables are almost always given single character names starting with the character 'i'. Nested loop variables are usually 'j', etc.
  5. Use const! If you have a global constant in your program, declare it as such by giving it a meaningful identifier and then refer to that constant using the identifier, rather than the literal value. For example, the number 24 has little meaning by itself, but if you use a constant called "NUM_GRADES" instead, it is clear what is meant.
  6. Name your constants in ALL CAPS to distinguish them from variables.
  7. Avoid global variables! Global variables make your code extremely difficult to step through, and debug. Don't use them.
  8. Use logical functions! Don't make a function for every little thing you need to do in your project. If there is a small bit of code that you need to execute from one place, dont' bother making a function. If you need to call the same code numerous times, or it is a stand-alone operation, separate it into a function. For example, even if you are only computing the factorial of a number from one place in your code, it probably makes sense to make it a function. The reason is that when reading through someone's code, it is much easier to understand the line "computeFactorial(5)" than it is to understand some odd loop structure that computes the factorial of 5. Especially since the programmer probably didn't folow the above spec about commenting the loop to compute the factorial.
  9. Document your variables! If a variable name doesn't fully describe its purpose in your program, comment it when you declare it! This will save enormous amounts of time later!
  10. 80 Columns! Don't extend anything (code OR comments) past the 80th column in your source files. This helps in printing and reading code in any editor anywhere.
  11. Use spaces! Don't use tabs to indent your code. This causes problems for many users, and also indents your code way more than necessary, so that after only indenting a few times, you are beyond the 80 column limit.
  12. Indent consistently! (see the first guideline above). If you choose to indent two spaces for every curly brace, then do it exactly that way every time. This helps so much in lining things up, and finding those pesky "unmatched }" errors. Note: I indent exactly two spaces every time, which doesn't result in too much extra whitespace.
  13. Use curly braces consistently! (see the first guideline above). There are a few different options for curly braces. Whichever you choose, always use the same standard. Don't put the opening curly brace on the same line as the "if" once, but then put it on the next line next time. My suggestion is always put both opening curly braces and closing curly braces on a line all by themselves, and make them line up with each other. The only other text that should ever be allowed to appear on a line with a curly brace is an optional comment describing what the brace starts or ends.