C++ Style Guidelinesby 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Name your constants in ALL CAPS to distinguish them from variables.
- Avoid global variables! Global variables make your code extremely
difficult to step through, and debug. Don't use them.
- 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.
- 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!
- 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.
- 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.
- 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.
- 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.