Difference between revisions of "Coding guidelines"
(→Use whitespace for clarity) |
(→Switch statement) |
||
| Line 13: | Line 13: | ||
=== Switch statement === | === Switch statement === | ||
| − | + | ||
| + | switch(alignment) | ||
| + | { | ||
| + | case EAlignment::EVIL: | ||
| + | do_that(); | ||
| + | break; | ||
| + | case EAlignment::GOOD: | ||
| + | do_that(); | ||
| + | break; | ||
| + | } | ||
=== Where to put spaces === | === Where to put spaces === | ||
Revision as of 13:50, 19 December 2011
Coding Guidelines
Style Guidelines
In order to keep the code consistent, please use the following conventions. From here on `good' and `bad' are used to attribute things that would make the coding style match, or not match. It is not a judgment call on your coding abilities, but more of a style and look call. Please try to follow these guidelines to ensure prettiness.
Indentation
Use 4 space tabs for writing your code (hopefully we can keep this consistent). If you are modifying someone else's code, try to keep the coding style similar. Switch statements have the case at the same indentation as the switch.
Switch statement
switch(alignment) { case EAlignment::EVIL:
do_that(); break;
case EAlignment::GOOD:
do_that(); break;
}
Where to put spaces
Use a space before and after the address or pointer character in a pointer declaration.
Good:
CIntObject * images[100];
Bad:
CIntObject* images[100]; or CIntObject *images[100];
Use whitespace for clarity
Use white space in expressions liberally, except in the presence of parenthesis.
Good:
if(a + 5 > method (blah ('a') + 4))
foo += 24;
Bad:
if(a+5>method(blah('a')+4))
foo+=24;
Between if, for, while,.. and the opening brace there shouldn't be a whitespace. The keywords are highlighted, so they don't need further separation.
Where to put braces
Inside a code block put the opening brace on the next line after the current statement:
Good:
if(a)
{
code ();
code ();
}
Bad:
if(a) {
code ();
code ();
}
Avoid using unnecessary open/close braces, vertical space is usually limited:
Good:
if(a)
code ();
Bad:
if(a) {
code ();
}
When defining a method, use a new line for the brace, like this:
Good:
void method()
{
}
Bad:
void Method() {
}
File headers
For any new files, please use a descriptive introduction, like this:
/* * Name_of_File.h, part of VCMI engine * * Authors: listed in file AUTHORS in main folder * * License: GNU General Public License v2.0 or later * Full text of license available in license.txt file, in main folder * */
The above notice have to be included only in header files (.h), except there is a cpp file with no corresponding header file.
Multiline comments
For long, multiline comments use the following style:
/* * Blah * Blah again * and another Blah */
Where and how to comment
Every class and all public methods should be commented. Methods should have additionally to the small summary what it does a description about all parameters and the return value. Good:
// This method is for… // Params: int x: That’s required for… // Return: double The calculated… double foo(int x);
The separation between the type and the name of a variable should not only be applied to method comments, but to variables declarations in classes/structs as well. Good:
int x; // blab la double f; // blab la
Casing
Local variables and methods start with a lowercase letter and use the camel casing. Classes/Structs start with an uppercase letter and use the camel casing as well. Macros and constants are written uppercase.
Line length
The line length for c++ source code is 120 columns. If your function declaration arguments go beyond this point, please align your arguments to match the opening brace. For best results use the same number of tabs used on the first line followed by enough spaces to align the arguments.
Warnings
Avoid use of #pragma to disable warnings. Compile at warning level 3. Avoid commiting code with new warnings.
Best practises
Loop handling
Use BOOST_FOREACH for iterating through every item of a container. It should be used in any case except if Visual Studio debug performance is important, then you may use a simple for loop to avoid use of STL Iterator checks.
The loop counter should be of type int, unless you are sure you won't need negative indices -- then use size_t.
Include guards
Use #pragma once instead of the traditional #ifndef/#define/#endif include guards.
Pre compiled header file
The header StdInc.h should be included in every compilation unit. It has to be included before any C macro and before any c++ statements. Pre compiled header should not be changed, except any important thing is missing. The StdInc includes most Boost libraries and nearly all standard STL and C libraries, so you don’t have to include them by yourself.
Type naming
Classes should be prefixed with an upper C, Interfaces with an upper I, Enumerations with an upper E, Structs with an upper S and typedefs with an upper T
Enumeration handling
Do not declare enumerations in global namespace. It is better to wrap them in class or namespace to avoid polluting global namespace:
namespace EAlignment
{
enum EAlignment { GOOD, EVIL, NEUTRAL };
}
Class handling
The following text is deprecated. Their will be a final decision about this point in the next days.
Every class should reside in its own compilation unit. Nested classes and structs are allowed to be placed in the same file. A class which gets included only once can be placed alongside with the “main” class (where it would be included). Class names and their file names should be named equally.
