150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
Coding standards
|
|
================
|
|
It is highly recommended to use a single *coding style* for the whole project
|
|
source code. Exceptions are allowed for external libraries used in the project,
|
|
but it is generally advisable all contributors to use this style.
|
|
|
|
Tab Size
|
|
--------
|
|
First of all, we use spaces. Tabs are four-character width. That is, no 8-space
|
|
tabs, no 2-space tabs. Four. Unfortunately there's no such thing as 'standard
|
|
tab width', and 4-space indenting looks best from our point of view, besides MSVC'
|
|
editor has this setting by default.
|
|
|
|
Line length
|
|
-----------
|
|
Then, please use 80-character wide lines. If your line is way longer than that,
|
|
please split it. If it's just a little longer, so be it. The continuation text,
|
|
if you're splitting text inside the brackets, should be indented to the position
|
|
after the opening bracket:
|
|
|
|
printf("This is a example of how we split lines longer than %d characters\n"
|
|
"into several so that they won't exceed this limit.\n",
|
|
max_sourcecode_width);
|
|
|
|
If you have long strings, you can split them as shown above, just remember that
|
|
C/C++ compilers will glue together several strings that come without any special
|
|
characters between them into one.
|
|
|
|
Brackets
|
|
--------
|
|
Now we use symmetric bracket placement, closing bracket under the opening bracket:
|
|
|
|
if (something)
|
|
{
|
|
...;
|
|
}
|
|
else
|
|
{
|
|
...;
|
|
}
|
|
|
|
switch (x)
|
|
{
|
|
case 1:
|
|
printf("X is one!\n");
|
|
break;
|
|
case 2:
|
|
{
|
|
printf("X is two!\n");
|
|
break;
|
|
}
|
|
}
|
|
|
|
for (int i = 1; i < 3; ++i)
|
|
{
|
|
printf("I is %i!\n", i);
|
|
}
|
|
|
|
Every bracketed block moves its contents by one tab to right. Labels (but not case
|
|
selectors or 'public:/private:/protected' C++ keywords) are placed at the leftmost
|
|
indention position for the current block, that is, in the same position where
|
|
enclosing brackets are.
|
|
|
|
Also please don't use brackets around a single statement because it clutters the
|
|
code with unneeded stuff; use brackets only when using non-obvious constructs,
|
|
like:
|
|
|
|
if (...)
|
|
{
|
|
if (...)
|
|
...;
|
|
}
|
|
else
|
|
...;
|
|
|
|
Also, please place one space before opening parenthesis. Before, but not after
|
|
(the `if ( blah )` style is a no-no!).
|
|
|
|
Class declaration and constructors
|
|
----------------------------------
|
|
Here is an example:
|
|
|
|
class Class : public Parent
|
|
{
|
|
public:
|
|
Class() : Parent(0),
|
|
m_field(1)
|
|
{
|
|
func();
|
|
}
|
|
|
|
void func() {}
|
|
|
|
private:
|
|
int m_field;
|
|
};
|
|
|
|
Please follow the following rules for classes:
|
|
|
|
* space before and after : in class parents list and constructor body
|
|
* next line and indent for class field initialization list
|
|
* indent for public:/private:/protected: section with additional indent
|
|
for section content
|
|
* empty or short function body can be at same line with declaration in
|
|
in-class definition case
|
|
|
|
Code documentation with Doxygen
|
|
-------------------------------
|
|
Now, please use DoxyGen-type comments. This is a bit similar to JavaDoc comments
|
|
and to other automatic code documentation generation tools. One-line documentation
|
|
should be placed in `///` (three slashes) comments if the comment is above the
|
|
function/member, if you want the comment on the same line you should use `///<`
|
|
instead, multi-line comments should be put in a `/** ... */` block (slash-two-stars).
|
|
|
|
Here's a example that shows most useful keywords that you can use in a comment block:
|
|
|
|
/**
|
|
* This function does something very useful. If used with care, this function
|
|
* has the potential to make your programs really really useful.
|
|
*
|
|
* \arg \c x
|
|
* The x argument specifies a integer that is transformed into something useful.
|
|
* \arg \c y
|
|
* This argument, if not NULL, is a pointer to a free memory area where this
|
|
* function will put something really really useful.
|
|
* \return
|
|
* A useful value, or NULL if error.
|
|
*
|
|
* Here is a example that you can paste into your code so that it saves you a
|
|
* lot of typing:
|
|
*
|
|
* \verb atim (Remove the space)
|
|
* for (int x = 0; x < 100; ++x)
|
|
* printf("DoSomethingUseful%d = %s\n", i,
|
|
* DoSomethingUseful(i, &ScratchPad));
|
|
* \endve rbatim (Remove the space)
|
|
*
|
|
* Paragraphs are split from each other by inserting a empty line. Also some HTML
|
|
* tags are supported, like <ol> [<li>...] </ol> and <ul> [<li>...] </ul> for
|
|
* ordered (numbered) and unordered (dotted) lists respectively.
|
|
*/
|
|
char *DoSomethingUseful(int x, void *y);
|
|
|
|
/// This is a one-line comment
|
|
void Something();
|
|
|
|
Use normal comments like `//` and `/* ... */` only if you want to make a comment
|
|
that should not go into the automatically annotated code (like:
|
|
`/* shit ... this does not work */`).
|