Difference between revisions of "Code Formatting Conventions"
(→Whitespaces: added rules for template definiton and operator overloading) |
m (→Whitespaces) |
||
Line 85: | Line 85: | ||
'''Template definitions''' | '''Template definitions''' | ||
no whitespace between template and < | no whitespace between template keyword and < | ||
<pre> | <pre> | ||
template<typename foo> | template<typename foo> |
Revision as of 22:49, 3 May 2008
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.
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.
In the following examples tabs are replaced by spaces for visual consistency with the Code Formatting Conventions. But in actual code, use tabs for indentions (our tabs are assumed to be 4 spaces wide).
Hugging braces
Braces in your code should look like the following example:
if (int i = 0; i < t; i++) { [...] } else { [...] } class Dummy() { [...] }
Did you see the {}'s on that?
Tab indents, with tabstop at four spaces
Says it all, really.
Whitespaces
Conventional operators surrounded by a space character
a = (b + c) * d;
C++ reserved words separated from opening parentheses by a white space
while (true) {
Commas followed by a white space
someFunction(a, b, c); int d, e;
Semicolons followed by a space character, if there is more on line
for (int a = 0; b++; c < d) doSomething(e); doSomething(f); // This is probably bad style anyway
When declaring class inheritance and in a ? construct, colons should be surrounded by white space
class BusWheel : public RubberInflatable { (isNight) ? colorMeDark() : colorMeBright();
Indentation level is not increased after namespace clause
namespace Scumm { byte Actor::kInvalidBox = 0; void Actor::initActorClass(ScummEngine *scumm) { _vm = scumm; } } // End of namespace Scumm
array delete operator has no whitespace before []
delete[] foo;
Template definitions
no whitespace between template keyword and <
template<typename foo> void myFunc(foo arg) { // ... }
Operator overloading
no whitespace between operator name and opening parentheses on definition (like with normal function/method definitions)
bool operator==(const MyType &l, const MyType &r) { // ... }
Switch / Case constructs
switch (cmd) { case kSaveCmd: save(); break; case kLoadCmd: case kPlayCmd: close(); break; default: Dialog::handleCommand(sender, cmd, data); }
Naming
Constants
Basically, you have two choices:
kSomeKludgyConstantName // notice k prefix
or
SOME_KLUDGY_CONSTANT_NAME
Classes
Mixed case starting with upper case
class MeClass() {
Class members
_ prefixed and in mixed case (Yo! no underscore separators), starting with lowercase.
char *_someVariableName;
Class methods
mixed case, starting with lowercase.
void thisIsMyFancyMethod();
Special comments
Special Keywords
The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certain sections of our code. In particular:
- FIXME marks code that contains hacks or bad temporary workarounds, things that really should be revised at a later point.
- TODO marks incomplete code, or things that could be done better but are left for the future.
- WORKAROUND marks code that works around bugs in the original game, like script bugs. Sometimes these bugs worked in the original due to bugs in the original engine, sometimes the bug was visible in the original, too. It's important that you explain here what exactly you work around, and if applicable, refer to relevant tracker items!
Doxygen documentation comments
ScummVM uses the Doxygen software to generate HTML documentation for the codebase (available here).
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.
There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:
/** * Move ("warp") the mouse cursor to the specified position in virtual * screen coordinates. * @param x the new x position of the mouse * @param y the new x position of the mouse */ virtual void warpMouse(int x, int y) = 0;
(view the generated documentation here).
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 @.
For more information, visit the official documentation: