Coding Guidelines

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

Coding guidelines for code layout an 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
  • Member functions should be CamelCase
  • Regular functions can be all_lowercase if meant to by standard tool functions, to fit in with C++ built-in libraries.
  • User-defined types should be CamelCase
  • Constants should be ALL_UPPERCASE, with words separated by underscores
  • Templated types 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 bases on Emscripten Limitations:

• Try to avoid use of 64-bit integers (that is, the "long long" type). Emscripten has to emulate these an it 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.

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