The reason for me to write this article is the fact that many people don't seem to know (or care) about code readability. Readability is the base for portability, re-usability and understandability (!).
Without proper code you cannot ask help on these forums without getting complaints, so read carefully; these are some tips and tricks to clean up your code.
This is a guideline, I do not say this is perfect. I just place a good way to do it, it's up to you to decide if you use it or not.
This guide is not considered complete but should help you well on your way, all suggestions are welcome.
On Brackets
Always put brackets on a empty line and put opening and closing brackets on the same "height" in your code. Anything that goes in between the two brackets should be tabbed to the right by a number which is consistent over all your code. (I use 4 spaces in my example) This style of bracketing is called, Allman style.
1 2 3 4 5 6 7 8 9 10 11 12 13
|
#include <iostream>
using std::cout;
using std::endl;
int main()
{
for(int i = 0; i < 9; i++)
{
cout << i << endl;
}
return 0;
}
|
There are, of course, other ways to do this. One is a slight variation of the Allman style: Whitesmith style. The brackets are put on the same level as the inner statements.
1 2 3 4 5 6 7 8 9 10 11 12 13
|
#include <iostream>
using std::cout;
using std::endl;
int main()
{
for(int i = 0; i < 9; i++)
{
cout << i << endl;
}
return 0;
}
|
When it is not important to see the text clearly, but rather see how different statements relate to one another (mainly if/else relationships), you can also use 1TBS (The One True Brace Style):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
|
#include <iostream>
using std::cout;
using std::endl;
int main()
{
for(int i = 0; i < 9; i++)
{
// Allman, up to now, time to go 1TBS for If/Else
if (i < 5) {
cout << i << endl;
} else {
cout << i*2 << "\t";
} // And of if/else clause, the last bracket is the only one that takes up it's own line
// Allman again
}
return 0;
}
|
On Comments
Commenting is done to improve readability, but it is also possible to make your comments more readable. Use multi-line comments only when needed and avoid putting comments at the end of code lines. Avoid tabbing your comments, use newlines to make things clearer. See On Consistency for more information.
The following comments may seem worthless, but I'm just trying to make clear what I told above.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
|
#include <iostream>
using std::cout;
using std::endl;
int main()
{
// Count
for(int i = 0; i < 9; i++)
{
cout << i << endl;
}
// Program termination
return 0;
}
|
On Consistency (General)
When different alternatives achieve the same result (at the same speed and both in the same amount of code lines), assure that you remain consistent to a single method. This applies to post- and prefix additions and subtractions (++ / --), as well as functional and C-style conversions int() and (int).
Whatever you do, be consistent.
On Function Calls (and definitions)
Spaces are all we will talk about on this subject. Be consistent with them. Generally, don't put spaces before or after parenthesis. Use them only after a comma (and only put a single one, in that case).
power(3, 5)
On Initialization
Consistency applies to initializations, too:
When given the choice between initializing at the start or later, use a single method. If you, however are left without a choice on which to use, use which ever you need. Furthermore, use proper spacing when creating pointers or references (or references to pointers to pointers to pointers to references to blablabla).
Any of the following are fine, but just use ONE style for all of your code.
1 2 3 4
|
int**& Variable;
int **& Variable;
int **&Variable;
int** &Variable;
|
On Naming
The following is a guideline and is open for change (as long as it's consistent, of course).
Naming is important for functions, classes, structures, unions, variables, namespaces and so on.
How to do good naming?
1. Make sure you name things by what they do (or are).
2. Possibly prefix them by a one or two lowercase character that describes the named instance. (c for classes, s for strings, i for integers, d for doubles, etc)
3. Start every word with a uppercase character and use lowercases for the rest. (An integer could become: iNumber)
A single exception to these rules are loop-variables. These are often named by a single lowercase character.
On Operators
Operators that are used for comparison and assignment should always be post and prefixed by a single space, other (arithmetic) operators have no generally accepted spacing usage. If you, however get very complicated statements by the lack of spaces, use them where you want them. (Two exceptions of this rule are << and >>, but ONLY when they are used for in- and output streams)
1 2
|
int iNumber = 6+5;
int iReturnValue = 4*iNumber +3;
|
On Preprocessor Directives
All spacing and newline rules apply here. For #define, however, make sure you make them differentiable from normal variables (making their names entirely uppercase is one method to do so, pre- AND postfixing their names with _ is another. You are free to do whatever you want, just keep things clear.)