When writing code in languages like C / C++, it's always important to keep a consistent coding style througout a single project. When a project looks like multiple people (or a single skitzoid) wrote the code, it can be much more difficult to read.
Here is the Church Of Agile's recommended coding style.
No tabs.
All source code (when indented) is indented by 2 spaces. Using tabs can make code difficult to line up. Take the following code for example:
if (color == RED ||
color == BLUE)
{
}
It's possible that indenting the second portion of the if statement takes a tab plus an extra space. Also if one developer uses an editor that treats a tab as 4 spaces but other person uses an editor that uses 2 spaces, things won't line up the same.
No egyptian brackets.
The opening and closing { } should line up (also called Allman style) unless they are one line.
if (something) {
}
Should be written as:
if (something)
{
}
Lined up code is symmetrical and a lot easier on the brain. If you're up late working extra hours on a project it's subconsciously going to make your life easier.
No extra parenthesis.
if ((something == 1) || (something == 3))
{
}
Should be written as:
if (something == 1 || something == 3)
{
}
If someone accidently forgets the == and does = instead, if there are extra parenthesis it will set the variable instead of checking it causing a bug. Too many parenthesis can also be tough to look at.
Single line if's should have { }
if (something) break;
Or possibly:
if (something)
break;
Should be written as
if (something) { break; }
The first example is not that bad, but the second one with the break on the line below the if statement can look quite confusing.
No skitzophrenic comments.
Comments should never have the word "we" or "us" in them unless it's a personal comment.
// Now we are going to the compute the sum of the array
Should be written as:
// Now compute the sum of the array.
A personal comment example would be:
// FIXME: I wasn't sure how to compute the sum of an array so I did this.
No pointless comments.
If you think someone is going to say sarcastically "Really? Is that what's the for?" then there is no need to add a comment for it. It's just noise. Some examples:
#include "config.h" // for configuration file access
#include <string> // for std::string
No comments in the middle of if statement blocks.
Never put a comment before an else-if line breaking up the first block with the second.
if (something)
{
...
}
// If the color is red.
else if (color == RED)
{
Should be written as:
if (something)
{
...
}
else if (color == RED)
{
// If the color is red.
This comment is also breaking the rule of pointless comments. The if statement makes this obvious already.
No comments at the end of statements.
length = (length + 7) & ~7; // align to 8-bytes
Should be written as:
// Align to 8-bytes.
length = (length + 7) & ~7;
Put comments above the code it's commenting on.
Comments should start with a capital letter and end with a period and have a space after the //.
//return if outputting only colors
Should be written as:
// Return if outputting only colors.
Comments shouldn't ask questions.
// Write to a binary output file?
if (file->HasOutputFile())
{
Are you asking me or telling me? This should be written as:
// If needed, write to binary output file.
if (file->HasOutputFile())
{
Comments shouldn't yell.
// THERE'S NO REASON TO PANIC!!!!!!!!!!!!!!!!!!!!
Please no comments in all caps and no need for !
If some piece of code needs attention for later, the keywords FIXME: and REVIEW: with a small comment are helpful and make it possible to grep for these issues later. Vim will highlight FIXME in yellow.
No Yoda conditions.
if (2 == n)
Should be written as:
if (n == 2)
Do not leave space at the end of lines.
Running git diff will color extra spaces at the end of lines red, but in vim doing: /s $ will search for all lines that end in spaces. Those extra spaces should be deleted before commiting.
In C/ C++ the * and & always go against the variable it's modifying. In C# and Java the * or [] goes with the type.
char* s;
In C++ should be written as
char *s;
The reasoning is, C (and therefore C++) was designed so the * is an attribute for the variable it's modifying. For example in:
int *color, brightness;
The 'color' variable is a pointer but brightness is not. In C# this (and Java) was changed so that int* color, brightness; would make both color and brightness pointers. Or int[] a, b; would make both a and b references.
int[] color, brightness;
Place 1 single blank line between "paragaphs" of code.
if (a == 1)
{
do_something();
}
if (b == 1)
{
do_something_else();
}
Should be written as:
if (a == 1)
{
do_something();
}
if (b == 1)
{
do_something_else();
}
In the first example it's sometimes confusing (especially coding late at night tired) that the first and second if statements don't go together.
Place 1 space after the keywords "while", "switch", "for", and "if".
if(something == 3)
{
while(k == 1)
{
...
}
}
Should be written as:
if (something == 3)
{
while (k == 1)
{
...
}
}
Leave a space in expressions.
int a = b[i+i]+6;
Should be written as
int a = b[i + i] + 6;
It's again just easier for tired eyes to read.
Attempt to name object variables by the class or struct.
Color *color;
The class names are always camel case and the variable names are lower case with a space separating words. This will help avoid someone having to scroll to the declaration of variables (probably the top of a function) to figure out how the Color variable in the function is named.
Don't creatively remove letters from variables.
An example:
int colr;
Should be spelled out as:
int color;
If other developers are constantly having backtrack inside a function to figure out how a variable is spelled, it's a waste of time (aka money). If everyone names their variables that mean the same thing different in different functions or even files, it can be even more time consuming.
80 columns.
When opening up a new terminal, it should open up to 80 columns. The recommendation is to *try* to make sure that source code (and especially comments) don't pass 80 columns. Sometimes it's not possible, and that's probably okay, but just try.
One hint that sometimes helps is if there is a long expression in an if statement or such, defining a const variable above the if statement with part of the expression can have 0 performance cost and might make the code easier to read in various situations.
if (((color_item->m_colorspace == COLORSPACE_YUV) ||
(color_item->m_colorspace == COLORSPACE_RGB)) &&
(LIGHT_SOURCE_BASE(((LightSource *)color_item->m_context)->m_light_type) == LIGHT_SOURCE_BULB))
Could be written as:
const LIGHT_TYPE light_type =
((LightSource *)color_item->m_context)->m_light_type;
if ((color_item->m_colorspace == COLORSPACE_YUV ||
color_item->m_colorspace == COLORSPACE_RGB) &&
LIGHT_SOURCE_BASE(light_type) == LIGHT_SOURCE_BULB))
Line stuff up.
Try to make code look straight.
if (house.color == COLOR_RED &&
house.size == SIZE_MANSION)
{
return true;
}
Could be written as:
if (house.color == COLOR_RED &&
house.size == SIZE_MANSION)
{
return true;
}
Crooked code is sometimes harder to read and diffcult on tired eyes.
Organize public, protected, private.
There should only be one definition of public, protected, and private (in this order) in a class. There are few exceptions for that rule when it's okay.
Functions should always go above variables and variables should typically be private with accessor methods that start with "Get", "Set", "Is", etc. An example is:
Functions always come first in a public / protected / private block. Member variables are defined under the functions.
class Something
{
public:
Something();
~Something();
int GetFirst() { return first; }
int GetSecond() { return second; }
bool IsEqual() { return first == second; }
int data;
protected:
int first;
private:
ProcessData();
int second;
};
Speak English that everyone understands.
Try to use simple English when naming variables, functions, and classes. It might be fun to use a thesaurus to come up with creative words to use, but your coworkers may not have your inflated vocabulary. Maybe English isn't their first language. If developers are constantly having to look up words to figure out what a piece of code does it's a waste of time (aka company money).