Coding Guidelines

These need to be better organized, but some basic guidelines are presented below.

Coding guidelines for code layout and naming schemes:

• All code should be in header files for ease of inclusion into Emscripten projects.

• Files that define a single class should be named after that class. Files that define sets of functions or multiple classes should have an all-lowercase name that describes its contents.

• All files and all directories must be levelized. This is partly enforced through all files being headerfiles (and thus we cannot have circular dependencies), but for clean coding practices (and easy of unit testing) whole directories should not refer to each other bidirectionally either. See Large-Scale C++ Software Design by John Lakos for a strong pro-levelization argument.

• In-code identifier formatting is always hard to settle upon. The guidelines below are for consistency.

  • Variable names should be all_lowercase, with words separated by underscores
  • Function names should be CamelCase() unless they are meant to mimic a function from the C++ standard library, at which point they can be all_lowercase to fit in.
  • User-defined types should be CamelCase
  • Constants should be ALL_UPPERCASE, with words separated by underscores
  • Template parameters should be ALL_UPPERCASE.
  • Typedefs should match the casing of the types they are aliasing. For example, a typedef on a template parameter might be all uppercase, while a typedef on a user-defined type should be CamelCase.

Coding guidelines based on Emscripten Limitations:

• Try to avoid use of 64-bit integers (that is, the "long long" type). Emscripten has to emulate these and they can cause a notable slowdown.

• Do not rely on exceptions when possible. Emscripten is slow at dealing with them and they can slow down code even when not triggered.

• Do not write multi-threaded code that uses shared state. Javascript cannot (yet) handle such code and as such Emscripten cannot compile it. Note that Emscripten does have experimental support of pthreads.

• Obviously, do not use any architecture-specific tricks, such as assuming endianness, doing unaligned reads or writes, directly accessing registers, etc.