Code Formatting Conventions: Difference between revisions
No edit summary |
No edit summary |
||
Line 7: | Line 7: | ||
This is an example of the layout & indention style we encourage. | This is an example of the layout & indention style we encourage. | ||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
// somefile.hpp | |||
namespace SomeSpace | namespace SomeSpace | ||
{ | { | ||
Line 16: | Line 17: | ||
public: | public: | ||
float someFunction(float p1, float p2) const; | float someFunction(float p1, float p2) const; | ||
int getSomeVar() const { return mSomeVar; } // Allowed only for one-liner getters and setters. | |||
void setSomeVar(int v) { mSomeVar = v; } // All other functions should be implemented in somefile.cpp. | |||
}; | }; | ||
} | } | ||
// somefile.cpp | |||
namespace SomeSpace | namespace SomeSpace | ||
{ | { | ||
Line 29: | Line 34: | ||
Note that the indention width is 4 spaces. If you use tabs instead of spaces, our build server will reject your code. Mixing spaces and tabs is '''not''' good. | Note that the indention width is 4 spaces. If you use tabs instead of spaces, our build server will reject your code. Mixing spaces and tabs is '''not''' good. | ||
Trailing spaces are unwanted, but avoid fixing it in existing code if there are no other changes in the same block of code. | |||
==General code formatting== | |||
<syntaxhighlight> | |||
if (x > 0) | |||
doSomething(); // CORRECT | |||
if (x > 0) | |||
{ | |||
doSometing(); // CORRECT | |||
} | |||
if (someCondition1() && someCondition2() | |||
&& someCondition3() && someCondition4()) // CORRECT | |||
{ | |||
doSomething(); | |||
} | |||
if (x > 0) doSomething(); // WRONG! | |||
if (x > 0) { | |||
doSomething(); // WRONG! | |||
} | |||
if (someCondition1() && someCondition2() | |||
&& someCondition3() && someCondition4()) // WRONG! | |||
doSomething(); | |||
</syntaxhighlight> | |||
==Includes== | ==Includes== |
Latest revision as of 19:29, 28 June 2020
In the beginning of OpenMW we did not have any code formatting conventions, which resulted in substantial inconsistencies. This page tries to codify the conventions that are most commonly used in the code base. Please stick to them, even if the code in the neighbourhood of what you are working on is not.
Layout & Indention
This is an example of the layout & indention style we encourage.
// somefile.hpp
namespace SomeSpace
{
class SomeClass
{
private:
int mSomeVar;
public:
float someFunction(float p1, float p2) const;
int getSomeVar() const { return mSomeVar; } // Allowed only for one-liner getters and setters.
void setSomeVar(int v) { mSomeVar = v; } // All other functions should be implemented in somefile.cpp.
};
}
// somefile.cpp
namespace SomeSpace
{
float SomeClass::someFunction(float p1, float p2) const
{
return p1 + p2;
}
}
Note that the indention width is 4 spaces. If you use tabs instead of spaces, our build server will reject your code. Mixing spaces and tabs is not good.
Trailing spaces are unwanted, but avoid fixing it in existing code if there are no other changes in the same block of code.
General code formatting
if (x > 0)
doSomething(); // CORRECT
if (x > 0)
{
doSometing(); // CORRECT
}
if (someCondition1() && someCondition2()
&& someCondition3() && someCondition4()) // CORRECT
{
doSomething();
}
if (x > 0) doSomething(); // WRONG!
if (x > 0) {
doSomething(); // WRONG!
}
if (someCondition1() && someCondition2()
&& someCondition3() && someCondition4()) // WRONG!
doSomething();
Includes
An implementation file (cpp) should always start by including its own header.
Further includes should be grouped. Groups must be separated by an empty line.
Standard C and C++ headers
Example:
#include <string>
C headers (if any) should be listed before the C++ headers.
External libraries headers
#include <osg/Vec3f>
If more than one external library is used, each library's headers should be put into a separate group.
Components headers
#include <components/compiler/context.hpp>
Apps headers
#include <mwworld/world.hpp>
Local headers
#include "world.hpp"
Doxygen Comments
Class definitions and function declarations should have doxygen comments. We aren't very strict about this though (especially for trivial functions).
A class should be documented like this:
/// \brief short description
///
/// Longer description.
class SomeClass
The longer description can be skipped, if there is nothing more to say.
A function should be documented like this:
/// Description.
void someFunction();
Here is a link to the Doxygen Documentation. Please make plenty of use of the listed commands, especially the following:
- \a
- \attention
- \brief
- \note
- \p
- \param
- \return
- \todo