1,554
edits
Difference between revisions of "Coding Conventions"
Jump to navigation
Jump to search
m
Fix code highlighting
(→Language features: Mention C++98 explicitly) |
m (Fix code highlighting) |
||
| Line 49: | Line 49: | ||
The second issue concerns problems causing engines to be non-reentrant. Consider a code snippet like this: | The second issue concerns problems causing engines to be non-reentrant. Consider a code snippet like this: | ||
< | <source lang="cpp"> | ||
bool foo(bool cond) { | bool foo(bool cond) { | ||
static bool bar = false; | static bool bar = false; | ||
| Line 56: | Line 56: | ||
return bar; | return bar; | ||
} | } | ||
</ | </source> | ||
Suppose this function is part of engine quux. When a new game using this engine is started, foo(false) will initially always return false. After foo(true) has been called the first time, foo will always return true. Maybe foo(true) is called when the user/player solves a certain puzzle in the game, and maybe the foo() function is meant to test whether this puzzle has already been solved. | Suppose this function is part of engine quux. When a new game using this engine is started, foo(false) will initially always return false. After foo(true) has been called the first time, foo will always return true. Maybe foo(true) is called when the user/player solves a certain puzzle in the game, and maybe the foo() function is meant to test whether this puzzle has already been solved. | ||
Now imagine the player uses the "return to launcher" feature; once back in the launcher, they restart the game, again using the quux engine. | Now imagine the player uses the "return to launcher" feature; once back in the launcher, they restart the game, again using the quux engine. | ||
| Line 62: | Line 62: | ||
This is another important reason why global variables keeping state are dangerous. At the very least, you ''must'' re-init any global variables whenever your engine starts. Relying on one-time initialization assignments to global variables, as in | This is another important reason why global variables keeping state are dangerous. At the very least, you ''must'' re-init any global variables whenever your engine starts. Relying on one-time initialization assignments to global variables, as in | ||
< | <source lang="cpp"> | ||
static int myGlobal = 0; | static int myGlobal = 0; | ||
</ | </source> | ||
is ''not'' sufficient. | is ''not'' sufficient. | ||
| Line 70: | Line 70: | ||
In addition, global variables are strongly discouraged; if they are to be used, then they ''must'' be accompanied by a comment that explains why this static variable is necessary, and why it cannot be replaced by something else, like typically a member variable of a suitable class / object. The comment should also indicate where the variable is (re)set when the engine launches. If no such comment is present, a generic comment of the following form shall be added to the variable declaration: | In addition, global variables are strongly discouraged; if they are to be used, then they ''must'' be accompanied by a comment that explains why this static variable is necessary, and why it cannot be replaced by something else, like typically a member variable of a suitable class / object. The comment should also indicate where the variable is (re)set when the engine launches. If no such comment is present, a generic comment of the following form shall be added to the variable declaration: | ||
< | <source lang="cpp"> | ||
// FIXME: non-const global var | // FIXME: non-const global var | ||
</ | </source> | ||
As a minor exception, if an existing engine uses many globals (due to not (yet) being objectified), it is permissible to use a single comment to document multiple globals at once. | As a minor exception, if an existing engine uses many globals (due to not (yet) being objectified), it is permissible to use a single comment to document multiple globals at once. | ||