Difference between revisions of "Coding Conventions"

Jump to navigation Jump to search
54 bytes added ,  15:01, 25 October 2018
m
Text replacement - "<source lang=" to "<syntaxhighlight lang="
(→‎Struct packing: -- code highlighting)
m (Text replacement - "<source lang=" to "<syntaxhighlight lang=")
Line 29: Line 29:
Do *not* assume that structs are stored in a certain way in memory -- the layout of a struct in memory can vary a lot between platforms, and on most modern systems it will almost never be "packed". If you absolutely must use packed structs, do not just use some #pragma or __attribute__ (as that is not portable either). Instead, do the following:
Do *not* assume that structs are stored in a certain way in memory -- the layout of a struct in memory can vary a lot between platforms, and on most modern systems it will almost never be "packed". If you absolutely must use packed structs, do not just use some #pragma or __attribute__ (as that is not portable either). Instead, do the following:
* Before the struct(s) you need to be packed, insert
* Before the struct(s) you need to be packed, insert
<source lang="cpp">
<syntaxhighlight lang="cpp">
   #include "common/pack-start.h" // START STRUCT PACKING
   #include "common/pack-start.h" // START STRUCT PACKING
</source>
</source>
* After the struct(s) you need to be packed, insert
* After the struct(s) you need to be packed, insert
<source lang="cpp">
<syntaxhighlight lang="cpp">
   #include "common/pack-end.h" // END STRUCT PACKING
   #include "common/pack-end.h" // END STRUCT PACKING
</source>
</source>
* At the "end" of each struct you need to be packed, insert the following between the closing } and the ; after it:
* At the "end" of each struct you need to be packed, insert the following between the closing } and the ; after it:
<source lang="cpp">
<syntaxhighlight lang="cpp">
   PACKED_STRUCT
   PACKED_STRUCT
</source>
</source>
Line 54: Line 54:


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">
<syntaxhighlight lang="cpp">
   bool foo(bool cond) {
   bool foo(bool cond) {
     static bool bar = false;
     static bool bar = false;
Line 67: Line 67:


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">
<syntaxhighlight lang="cpp">
   static int myGlobal = 0;
   static int myGlobal = 0;
</source>
</source>
Line 75: Line 75:


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">
<syntaxhighlight lang="cpp">
   // FIXME: non-const global var
   // FIXME: non-const global var
</source>
</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.
TrustedUser
2,071

edits

Navigation menu