|
|
| (79 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | = Coding Guidelines =
| + | {{Template:MovedToWebpage|https://vcmi.eu/developers/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 ===
| |
| − | | |
| − | <syntaxhighlight lang="cpp">
| |
| − | switch(alignment)
| |
| − | {
| |
| − | case EAlignment::EVIL:
| |
| − | do_that();
| |
| − | break;
| |
| − | case EAlignment::GOOD:
| |
| − | do_that();
| |
| − | break;
| |
| − | }
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | === Where to put spaces ===
| |
| − | | |
| − | Use a space before and after the address or pointer character in a pointer declaration.
| |
| − | | |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">CIntObject * images[100];</syntaxhighlight>
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">CIntObject* images[100]; or
| |
| − | CIntObject *images[100];</syntaxhighlight>
| |
| − | | |
| − | | |
| − | === Use whitespace for clarity ===
| |
| − | | |
| − | Use white space in expressions liberally, except in the presence of parenthesis.
| |
| − | | |
| − | '''Good:'''
| |
| − | <syntaxhighlight lang="cpp">if(a + 5 > method (blah ('a') + 4))
| |
| − | foo += 24;</syntaxhighlight>
| |
| − | | |
| − | '''Bad:'''
| |
| − | <syntaxhighlight lang="cpp">if(a+5>method(blah('a')+4))
| |
| − | foo+=24;</syntaxhighlight>
| |
| − | | |
| − | 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:
| |
| − | <syntaxhighlight lang="cpp">if(a)
| |
| − | {
| |
| − | code ();
| |
| − | code ();
| |
| − | }</syntaxhighlight>
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">if(a) {
| |
| − | code ();
| |
| − | code ();
| |
| − | }</syntaxhighlight>
| |
| − | | |
| − | Avoid using unnecessary open/close braces, vertical space is usually limited:
| |
| − | | |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">if(a)
| |
| − | code ();</syntaxhighlight>
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">if(a) {
| |
| − | code ();
| |
| − | }</syntaxhighlight>
| |
| − | | |
| − | When defining a method, use a new line for the brace, like this:
| |
| − | | |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">void method()
| |
| − | { | |
| − | }</syntaxhighlight>
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">void Method() {
| |
| − | }</syntaxhighlight>
| |
| − | | |
| − | When allocating objects, don't use parentheses for creating stack-based objects by zero param c-tors to avoid c++ most vexing parse and use parentheses for creating heap-based objects.
| |
| − | | |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">std::vector<int> v;
| |
| − | CGBoat btn = new CGBoat();</syntaxhighlight>
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">std::vector<int> v(); // shouldn't compile anyway
| |
| − | CGBoat btn = new CGBoat;</syntaxhighlight>
| |
| − | | |
| − | === File headers ===
| |
| − | | |
| − | For any new files, please use a descriptive introduction, like this:
| |
| − | <syntaxhighlight lang="cpp">/*
| |
| − | * 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
| |
| − | *
| |
| − | */</syntaxhighlight>
| |
| − | 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:
| |
| − | <syntaxhighlight lang="cpp">/*
| |
| − | * Blah
| |
| − | * Blah again
| |
| − | * and another Blah
| |
| − | */</syntaxhighlight>
| |
| − | | |
| − | | |
| − | | |
| − | === Where and how to comment ===
| |
| − | | |
| − | Every class and all methods should be commented. We follow the javadoc commenting style. See here for more details: http://www.stack.nl/~dimitri/doxygen/commands.html Methods should have a brief summary(mostly one sentence), optionally a longer description and a description about their parameters and the return value.
| |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">
| |
| − | /**
| |
| − | * This method is for…
| |
| − | *
| |
| − | * @param x That’s required for…
| |
| − | * @param foo there is no alignment here...
| |
| − | * @return the calculated…
| |
| − | */
| |
| − | double foo(int x, int foo);</syntaxhighlight>
| |
| − | | |
| − | Class members should be commented as well.
| |
| − | <syntaxhighlight lang="cpp">
| |
| − | /** bla bla */
| |
| − | int x;
| |
| − | | |
| − | /** when commenting a class member then try to summarize the purpose of it in one line */
| |
| − | double f;
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | === 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 practices ==
| |
| − | | |
| − | | |
| − | === Avoid code duplication ===
| |
| − | | |
| − | Avoid code duplication or don't repeat yourself(DRY) is the most important aspect in programming. Code duplication of any kind can lead to inconsistency and is much harder to maintain. If one part of the system gets changed you have to change the code in several places. This process is error-prone and leads often to problems. Here you can read more about the DRY principle: [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself http://en.wikipedia.org/wiki/Don%27t_repeat_yourself]
| |
| − | | |
| − | === 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 without an prefix 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:
| |
| − | <syntaxhighlight lang="cpp">
| |
| − | namespace EAlignment
| |
| − | {
| |
| − | enum EAlignment { GOOD, EVIL, NEUTRAL };
| |
| − | } | |
| − | </syntaxhighlight>
| |
| − | | |
| − | === Avoid senseless comments ===
| |
| − | | |
| − | If the comment duplicates the name of commented member, it's better if it wouldn't exist at all. It just increases maintenance cost.
| |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">size_t getHeroesCount(); //gets count of heroes (surprise?)</syntaxhighlight>
| |
| − | | |
| − | | |
| − | === Class handling ===
| |
| − | | |
| − | There is no definitive rule which has to be followed strictly. You can freely decide if you want to pack your own classes, where you are programming on, all in one file or each in one file. It's more important that you feel comfortable with the code, than consistency overall the project. VCMI has several container class files, so if you got one additional class to them than just add it to them instead of adding new files.
| |
| − | | |
| − | === Functions and interfaces ===
| |
| − | | |
| − | Don't return const objects or primitive types from functions -- it's pointless. Also, don't return pointers to non-const game data objects from callbacks to player interfaces.
| |
| − | | |
| − | Bad:
| |
| − | <syntaxhighlight lang="cpp">
| |
| − | const std::vector<CGObjectInstance*> guardingCreatures (int3 pos) const;
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | Good:
| |
| − | <syntaxhighlight lang="cpp">
| |
| − | std::vector<const CGObjectInstance*> guardingCreatures (int3 pos) const;
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | == Sources ==
| |
| − | [http://www.mono-project.com/Coding_Guidelines Mono project coding guidelines]
| |
