Open main menu

Difference between revisions of "Code Formatting Conventions"

Bulk replace: syntax="C++" -> 'source="cpp" so that we don't have to use a custom syntax highlighting extension
m (typo)
(Bulk replace: syntax="C++" -> 'source="cpp" so that we don't have to use a custom syntax highlighting extension)
Line 11: Line 11:
Braces in your code should look like the following example:
Braces in your code should look like the following example:


<syntax type="C++">
<source lang="cpp">
for (int i = 0; i < t; i++) {
for (int i = 0; i < t; i++) {
     [...]
     [...]
Line 27: Line 27:
     [...]
     [...]
};
};
</syntax>
</source>


Did you see the {}'s on that?
Did you see the {}'s on that?
Line 39: Line 39:
'''Conventional operators surrounded by a space character'''
'''Conventional operators surrounded by a space character'''


<syntax type="C++">
<source lang="cpp">
a = (b + c) * d;
a = (b + c) * d;
</syntax>
</source>


'''C++ reserved words separated from opening parentheses by a white space'''
'''C++ reserved words separated from opening parentheses by a white space'''


<syntax type="C++">
<source lang="cpp">
while (true) {
while (true) {
</syntax>
</source>


'''Commas followed by a white space'''
'''Commas followed by a white space'''


<syntax type="C++">
<source lang="cpp">
someFunction(a, b, c);
someFunction(a, b, c);
</syntax>
</source>
<syntax type="C++">
<source lang="cpp">
int d, e;
int d, e;
</syntax>
</source>


'''Semicolons followed by a space character, if there is more on a line'''
'''Semicolons followed by a space character, if there is more on a line'''


<syntax type="C++">
<source lang="cpp">
for (int a = 0; b < c; d++)
for (int a = 0; b < c; d++)
</syntax>
</source>
<syntax type="C++">
<source lang="cpp">
doSomething(e); doSomething(f); // This is probably bad style anyway
doSomething(e); doSomething(f); // This is probably bad style anyway
</syntax>
</source>


'''Semicolons preceded by a space character, if it ends an empty loop body'''
'''Semicolons preceded by a space character, if it ends an empty loop body'''


It should also contain a comment to make it clear that the loop is intentionally empty.
It should also contain a comment to make it clear that the loop is intentionally empty.
<syntax type="C++">
<source lang="cpp">
while (i < length - 1 && array[++i] != item) ; // Look for index of item with an empty loop
while (i < length - 1 && array[++i] != item) ; // Look for index of item with an empty loop
</syntax>
</source>
The following syntax is also acceptable:
The following syntax is also acceptable:
<syntax type="C++">
<source lang="cpp">
while (i < length - 1 && array[++i] != item)
while (i < length - 1 && array[++i] != item)
; //this loop is intentionally empty
; //this loop is intentionally empty
</syntax>
</source>


'''When declaring class inheritance and in a ? construct, colons should be surrounded by white space'''
'''When declaring class inheritance and in a ? construct, colons should be surrounded by white space'''


<syntax type="C++">
<source lang="cpp">
class BusWheel : public RubberInflatable {
class BusWheel : public RubberInflatable {
</syntax>
</source>
<syntax type="C++">
<source lang="cpp">
(isNight) ? colorMeDark() : colorMeBright();
(isNight) ? colorMeDark() : colorMeBright();
</syntax>
</source>


'''Indentation level is not increased after namespace clause'''
'''Indentation level is not increased after namespace clause'''


<syntax type="C++">
<source lang="cpp">
namespace Scumm {
namespace Scumm {


Line 100: Line 100:


} // End of namespace Scumm
} // End of namespace Scumm
</syntax>
</source>


'''Array delete operator has no whitespace before []'''
'''Array delete operator has no whitespace before []'''
<syntax type="C++">
<source lang="cpp">
delete[] foo;
delete[] foo;
</syntax>
</source>


'''Template definitions'''
'''Template definitions'''


No whitespace between template keyword and <
No whitespace between template keyword and <
<syntax type="C++">
<source lang="cpp">
template<typename foo>
template<typename foo>
void myFunc(foo arg) {
void myFunc(foo arg) {
     // ...
     // ...
}
}
</syntax>
</source>


'''Operator overloading'''
'''Operator overloading'''


Operator keyword is NOT separated from the name, except for type conversion operators where it is required.
Operator keyword is NOT separated from the name, except for type conversion operators where it is required.
<syntax type="C++">
<source lang="cpp">
struct Foo {
struct Foo {
     void operator()() {
     void operator()() {
Line 130: Line 130:
     }
     }
};
};
</syntax>
</source>


'''Pointers and casts'''
'''Pointers and casts'''


No whitespace after a cast; and in a pointer, we write a whitespace before the star but not after it.
No whitespace after a cast; and in a pointer, we write a whitespace before the star but not after it.
<syntax type="C++">
<source lang="cpp">
const char *ptr = (const char *)foobar;
const char *ptr = (const char *)foobar;
</syntax>
</source>


'''References'''
'''References'''


We use the same rule for references as we do for pointers: use a whitespace before the "&" but not after it.
We use the same rule for references as we do for pointers: use a whitespace before the "&" but not after it.
<syntax type="C++">
<source lang="cpp">
int i = 0;
int i = 0;
int &ref = i;
int &ref = i;
</syntax>
</source>


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


<syntax type="C++">
<source lang="cpp">
switch (cmd) {
switch (cmd) {
case kSomeCmd:
case kSomeCmd:
Line 167: Line 167:
     Dialog::handleCommand(sender, cmd, data);
     Dialog::handleCommand(sender, cmd, data);
}
}
</syntax>
</source>
* Note comment on whether fall through is intentional.
* Note comment on whether fall through is intentional.


Line 185: Line 185:
Camel case starting with upper case.
Camel case starting with upper case.


<syntax type="C++">
<source lang="cpp">
class MyClass { /* ... */ };
class MyClass { /* ... */ };
struct MyStruct { /* ... */ };
struct MyStruct { /* ... */ };
typedef int MyInt;
typedef int MyInt;
</syntax>
</source>


'''Class member variables'''
'''Class member variables'''
Line 195: Line 195:
Prefixed with '_' and in camel case (Yo! no underscore separators), starting with lowercase.
Prefixed with '_' and in camel case (Yo! no underscore separators), starting with lowercase.


<syntax type="C++">
<source lang="cpp">
char *_someVariableName;
char *_someVariableName;
</syntax>
</source>


'''Class methods'''
'''Class methods'''
Line 203: Line 203:
Camel case, starting with lowercase.
Camel case, starting with lowercase.


<syntax type="C++">
<source lang="cpp">
void thisIsMyFancyMethod();
void thisIsMyFancyMethod();
</syntax>
</source>


'''Local variables'''
'''Local variables'''
Line 211: Line 211:
Use camel case (Yo! no underscore separators), starting with lowercase.
Use camel case (Yo! no underscore separators), starting with lowercase.


<syntax type="C++">
<source lang="cpp">
char *someVariableName;
char *someVariableName;
</syntax>
</source>


Note that for POD structures it is fine to use this rule too.
Note that for POD structures it is fine to use this rule too.
Line 221: Line 221:
In general you should avoid global variables, but if it can't be avoided, use 'g_' as prefix, camel case, and start with lowercase
In general you should avoid global variables, but if it can't be avoided, use 'g_' as prefix, camel case, and start with lowercase


<syntax type="C++">
<source lang="cpp">
int g_someGlobalVariable;
int g_someGlobalVariable;
</syntax>
</source>


== Special comments ==
== Special comments ==
Line 242: Line 242:
There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:
There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:


<syntax type="C++">
<source lang="cpp">
/**
/**
  * Move ("warp") the mouse cursor to the specified position in virtual
  * Move ("warp") the mouse cursor to the specified position in virtual
Line 250: Line 250:
  */
  */
virtual void warpMouse(int x, int y) = 0;
virtual void warpMouse(int x, int y) = 0;
</syntax>
</source>
(See [http://doxygen.scummvm.org/d9/df4/classOSystem.html#ecab84670def917107d6c1b5ca3b82c3 here] for the docs generated from this.)
(See [http://doxygen.scummvm.org/d9/df4/classOSystem.html#ecab84670def917107d6c1b5ca3b82c3 here] for the docs generated from this.)


Line 256: Line 256:


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:
<syntax type="C++">
<source 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
</syntax>
</source>
(See [http://doxygen.scummvm.org/d7/d66/structCommon_1_1Point.html#2d868735aeaaf391ce9b3df9232c031f here] for the docs generated from this.)
(See [http://doxygen.scummvm.org/d7/d66/structCommon_1_1Point.html#2d868735aeaaf391ce9b3df9232c031f here] for the docs generated from this.)


TrustedUser
2,147

edits