Difference between revisions of "Coding Conventions"

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

   #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

   #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:

   PACKED_STRUCT

   PACKED_STRUCT

</source>

</source>

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:

   bool foo(bool cond) {

   bool foo(bool cond) {

     static bool bar = false;

     static bool bar = false;

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

   static int myGlobal = 0;

   static int myGlobal = 0;

</source>

</source>

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:

   // 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.