Difference between revisions of "Code Formatting Conventions"

From ScummVM :: Wiki
Jump to navigation Jump to search
m (fine-tuning)
(Updated the explanation for our formatting conventions)
Line 1: Line 1:
== Use common sense ==
== Use common sense ==


These are conventions which we try to follow when writing code for ScummVM. They are this way mainly for reasons of taste, however, sticking to a common set of formatting rules also makes it slightly easier to read through our sources. If you want to submit patches, please try to follow these rules.  
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.


As such we don't follow these rules slavishly, in certain cases it is OK (and in fact favorable) to stray from them.
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.
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 ==
== Hugging braces ==

Revision as of 18:24, 19 February 2007

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

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

The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certains 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!