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 */`).