Code Formatting Conventions - Revision history

DrMcCoy: /* C++ Standard */

2018-10-07T14:17:29Z

C++ Standard

← Older revision		Revision as of 14:17, 7 October 2018
Line 12:		Line 12:
	== C++ Standard ==		== C++ Standard ==

	~~We mainly follow~~ the C++03 standard~~, but we also use C99-style known-width integer type. See src/common/types.h for details~~.		Among the three main repositories, xoreos, xoreos-tools and Phaethon, we're following three different versions of the C++ standard.

	~~Apart from that, we like to keep~~ the standard ~~as low as possible,~~ for ~~compatibility reasons. If there's a compelling reason~~, ~~you can of course use~~ C++11 ~~features. But please do so only if you absolutely have~~ to~~; if~~ the ~~rest of~~ the ~~codebase does something the old~~-~~fashioned way~~, it'~~s best to keep doing it that way~~. ~~For example~~, ~~don~~'~~t introduce auto variables just~~ for ~~the sake of an iterator for-loop~~.		* xoreos itself follows the oldest standard for now, C++03
			* xoreos-tools follows the C++11 standard
			* Phaethon follows the C++14 standard, due to the reliance on the relaxed constexpr rules in [https://woboq.com/blog/verdigris-qt-without-moc.html Verdigris]

			With xoreos-tools, we're currently in a C++11 trial period. If everything goes well, we're opening xoreos for C++11 as well.

	== Hugging braces ==		== Hugging braces ==

DrMcCoy: Add section "Include order"

2015-12-05T00:48:57Z

Add section "Include order"

← Older revision		Revision as of 00:48, 5 December 2015
Line 169:		Line 169:

	No trailing whitespace, at all. This means that lines should never end with spaces or tabs. Remove them. Empty lines should be completely empty; not even indenting tabs should be there.		No trailing whitespace, at all. This means that lines should never end with spaces or tabs. Remove them. Empty lines should be completely empty; not even indenting tabs should be there.

			== Include order ==

			Include directives should be grouped by subsystem, roughly ordered by specificity, from general to specific.

			The group order is as follows:

			* C++ versions of standard C headers
			* Standard C++ headers
			* Standard C headers
			* Library includes
			* src/common
			* src/aurora
			* src/graphics
			* src/sound
			* src/video
			* src/events
			* src/engines

			Each group is separated by an empty line. The includes within each group are again ordered roughly by specificity, with includes used by other includes first. But in a .cpp file implementing an interface specified in a .h file, the .h file sits ontop of its group.

			For example, these could be the include directives in src/engines/nwn/game.cpp:

			<syntaxhighlight lang="cpp">
			#include <cassert>

			#include <list>
			#include <map>

			#include "src/common/util.h"
			#include "src/common/ustring.h"
			#include "src/common/filelist.h"

			#include "src/aurora/types.h"
			#include "src/aurora/talkman.h"

			#include "src/engines/aurora/util.h"

			#include "src/engines/nwn/game.h"
			#include "src/engines/nwn/util.h"
			#include "src/engines/nwn/nwn.h"
			</syntaxhighlight>

	== Switch/Case constructs ==		== Switch/Case constructs ==

DrMcCoy: /* Whitespaces */ Foward-declaration namespaces indent

2015-12-05T00:36:35Z

Whitespaces: Foward-declaration namespaces indent

← Older revision		Revision as of 00:36, 5 December 2015
Line 109:		Line 109:

	} // End of namespace Scumm		} // End of namespace Scumm
			</syntaxhighlight>

			'''However, namespaces used solely for forward-declarations should indent'''

			<syntaxhighlight lang="cpp">
			namespace Aurora {
			namespace NWScript {
			class Object;
			}
			}
	</syntaxhighlight>		</syntaxhighlight>

DrMcCoy: /* Whitespaces */ Add note about trailing whitespace

2015-12-05T00:32:51Z

Whitespaces: Add note about trailing whitespace

← Older revision		Revision as of 00:32, 5 December 2015
Line 155:		Line 155:
	int &ref = i;		int &ref = i;
	</syntaxhighlight>		</syntaxhighlight>

			'''Trailing whitespace'''

			No trailing whitespace, at all. This means that lines should never end with spaces or tabs. Remove them. Empty lines should be completely empty; not even indenting tabs should be there.

	== Switch/Case constructs ==		== Switch/Case constructs ==

DrMcCoy: /* C++ Standard */ We use mainly C++03

2015-12-05T00:28:52Z

C++ Standard: We use mainly C++03

← Older revision		Revision as of 00:28, 5 December 2015
Line 12:		Line 12:
	== C++ Standard ==		== C++ Standard ==

	We mainly follow the C++98 standard, but we also use C99-style known-width integer type. See src/common/types.h for details.		We mainly follow the C++03 standard, but we also use C99-style known-width integer type. See src/common/types.h for details.

	Apart from that, we like to keep the standard as low as possible, for compatibility reasons. If there's a compelling reason, you can of course use C++11 features. But please do so only if you absolutely have to; if the rest of the codebase does something the old-fashioned way, it's best to keep doing it that way. For example, don't introduce auto variables just for the sake of an iterator for-loop.		Apart from that, we like to keep the standard as low as possible, for compatibility reasons. If there's a compelling reason, you can of course use C++11 features. But please do so only if you absolutely have to; if the rest of the codebase does something the old-fashioned way, it's best to keep doing it that way. For example, don't introduce auto variables just for the sake of an iterator for-loop.

DrMcCoy: /* Doxygen documentation comments */

2015-12-05T00:28:19Z

Doxygen documentation comments

← Older revision		Revision as of 00:28, 5 December 2015
Line 252:		Line 252:

	<syntaxhighlight lang="cpp">		<syntaxhighlight lang="cpp">
	/**		/** Move ("warp") the mouse cursor to the specified position in virtual
	* Move ("warp") the mouse cursor to the specified position in virtual		* screen coordinates.
	* screen coordinates.		*
	* @param x the new x position of the mouse		* @param x the new x position of the mouse.
	* @param y the new y position of the mouse		* @param y the new y position of the mouse.
	*/		*/
	virtual void warpMouse(int x, int y) = 0;		virtual void warpMouse(int x, int y) = 0;
Line 265:		Line 265:
	If you want to add a brief explanation of a variable or function ''after'' its declaration, this is the correct syntax:		If you want to add a brief explanation of a variable or function ''after'' its declaration, this is the correct syntax:
	<syntaxhighlight lang="cpp">		<syntaxhighlight lang="cpp">
	int16 x; ///< The horizontal part of the point		int16 x; ///< The horizontal part of the point.
	int16 y; ///< The vertical part of the point		int16 y; ///< The vertical part of the point.
	</syntaxhighlight>		</syntaxhighlight>

DrMcCoy: Make our indenting style more clear

2015-03-28T10:50:06Z

Make our indenting style more clear

← Older revision		Revision as of 10:50, 28 March 2015
Line 40:		Line 40:
	Did you see the {}'s on that?		Did you see the {}'s on that?

	== ~~Tab indents~~, ~~with tabstop at four~~ spaces ==		== Tabs for indenting, spaces for alignment ==

	Says it all, really.		Says it all, really.

DrMcCoy: Add small note about the C++ standard we use

2014-05-10T11:26:23Z

Add small note about the C++ standard we use

← Older revision		Revision as of 11:26, 10 May 2014
Line 9:		Line 9:

	In the following examples tabs are replaced by spaces for visual consistency with the Code Formatting Conventions. But in actual code, use tabs for indentations (our tabs are assumed to be 4 spaces wide).		In the following examples tabs are replaced by spaces for visual consistency with the Code Formatting Conventions. But in actual code, use tabs for indentations (our tabs are assumed to be 4 spaces wide).

			== C++ Standard ==

			We mainly follow the C++98 standard, but we also use C99-style known-width integer type. See src/common/types.h for details.

			Apart from that, we like to keep the standard as low as possible, for compatibility reasons. If there's a compelling reason, you can of course use C++11 features. But please do so only if you absolutely have to; if the rest of the codebase does something the old-fashioned way, it's best to keep doing it that way. For example, don't introduce auto variables just for the sake of an iterator for-loop.

	== Hugging braces ==		== Hugging braces ==

DrMcCoy: Add a link to our .uncrustifyrc

2013-09-15T19:20:28Z

Add a link to our .uncrustifyrc

← Older revision		Revision as of 19:20, 15 September 2013
Line 279:		Line 279:
	convert-tabs		convert-tabs
	</pre>		</pre>

			Alternatively, [https://github.com/xoreos/xoreos/blob/master/.uncrustifyrc this config file] for [http://uncrustify.sourceforge.net/ uncrustify] should also work as a starting point for our conventions. Again, you may still clean things up manually.

DrMcCoy: ScummVM->xoreos

2013-08-05T10:21:21Z

ScummVM->xoreos

← Older revision		Revision as of 10:21, 5 August 2013
Line 4:		Line 4:
	== Use common sense ==		== Use common sense ==

	These are conventions which we try to follow when writing code for ~~ScummVM~~. Sticking to a common set of formatting / indention rules makes it easier to read through our source base (which now exceed half a million lines of code by far, making this quite important). If you want to submit patches, please try to adhere to these rules.		These are conventions which we try to follow when writing code for xoreos. Sticking to a common set of formatting / indention rules makes it easier to read through our source base (which now exceed half a million lines of code by far, making this quite important). If you want to submit patches, please try to adhere to these rules.

	We don't always follow these rules slavishly, in certain cases it is OK (and in fact might be favorable) to stray from them. Applying common sense, as usual, is a good idea.		We don't always follow these rules slavishly, in certain cases it is OK (and in fact might be favorable) to stray from them. Applying common sense, as usual, is a good idea.
Line 239:		Line 239:
	=== Doxygen documentation comments ===		=== Doxygen documentation comments ===

	~~ScummVM~~ uses the [http://www.doxygen.org/ Doxygen] software to generate HTML documentation for the codebase ~~(available [http://doxygen.scummvm.org here])~~.		xoreos uses the [http://www.doxygen.org/ Doxygen] software to generate HTML documentation for the codebase.

	Doxygen supports ''documentation blocks''. These are specially-formatted comments that doxygen prints out in the generated documentation. They are similar in purpose to Java's JavaDoc or Python's docstrings.		Doxygen supports ''documentation blocks''. These are specially-formatted comments that doxygen prints out in the generated documentation. They are similar in purpose to Java's JavaDoc or Python's docstrings.
Line 254:		Line 254:
	virtual void warpMouse(int x, int y) = 0;		virtual void warpMouse(int x, int y) = 0;
	</syntaxhighlight>		</syntaxhighlight>
	~~(See [http://doxygen.scummvm.org/d9/df4/classOSystem.html#ecab84670def917107d6c1b5ca3b82c3 here] for the docs generated from this.)~~

	As shown in the example, documentation blocks also support several special commands such as '''param'''. Those are prefixed with either '''@''' or '''\''', but developers should always use '''@'''.		As shown in the example, documentation blocks also support several special commands such as '''param'''. Those are prefixed with either '''@''' or '''\''', but developers should always use '''@'''.
Line 263:		Line 262:
	int16 y; ///< The vertical part of the point		int16 y; ///< The vertical part of the point
	</syntaxhighlight>		</syntaxhighlight>
	~~(See [http://doxygen.scummvm.org/d7/d66/structCommon_1_1Point.html#2d868735aeaaf391ce9b3df9232c031f here] for the docs generated from this.)~~

	For more information, visit the official documentation:		For more information, visit the official documentation: