SpringLobby Code: Style Guide

  1. SpringLobby Code: Style Guide
    1. Formatting
    2. Strings: Which Ones and How to Use Them
      1. Types
      2. Translation
    3. Documentation (It's Good for You)
    4. Miscellaneous/Not Yet Categorized

Formatting

  • Tab width: four (4) spaces.
  • Line endings: UNIX-style (LF).
  • Indent style: Allman / Ansi

Strings: Which Ones and How to Use Them

Types

  • Never use wxString for network buffers.
  • Never use std::string outside network buffers. Any std::string should be converted to wxString as soon as possible.
    • Functions should neither pass nor accept std::string arguments or returns.
  • Logging functions accept wxFormatString arguments; never pass strings directly.

Translation

When you add a string constant in the code, please mark it with one of the following.

  • Use the _() macro to designate a string as translatable. This should be done in all cases where the string will be read by the user.
  • Use the _T() macro to mark string constants which should not be translated (localized) by the users. 
    wxString aTranslatableString(_("This is an example of a translatable string."));
wxString aFileName(_T("springlobby.conf"));
  • When converting a number to a string, use the TowxString function defined in utils.h. It handles decimal-place localization properly. You may explicitly specify the type to convert from like this 
    TowxString<Type>(value)
    If not explicitly set, Type is inferred from parameter type.

Documentation (It's Good for You)

Missing documentation and unclear code are issues that trouble many open-source projects. You can help SpringLobby avoid them.
Use Doxygen-style comments.

  • Document header files.
    • Document all classes, functions, and variables that are in header files. It's usually a good idea to document a class as you write it, so you don't have to go back and do it later.
  • Document source code.
    • Mark any to-do items with @todo items (in Doxygen documentation blocks) in the code itself.
    • Use normal comments to explain your flow of logic and reasoning.

Note: if creation of docs fails, update your Doxygen to current version (1.5.6)

Miscellaneous/Not Yet Categorized

  1. Don't put #include in class headers unless they are strictly necessary, use forward declaration and object pointers whenever possible unless they make a coding hell or risk memleaks.
  2. Always use RAII.
  3. Any new optional dependency lib class should be wrapped in #ifndef NO_LIBRARYNAME.
  4. wx code must be retro compatible with wx2.6 for the moment, such requirement might be dropped in the future.
  5. Don't pass allocated memory pointers around classes unless it can't be avoided strictly, ideally the few exceptions should only be "smart pointers" type.
  6. Separate all GUI code from core code.
  7. When passing references generated from pointers, add assertion triggers from the source function and try/catch blocks in the receiver
  8. Don't let the assertion signals pass uncaught for more than 2 function nests, this leads to confused code and has high risk of leaving them uncaught when the functions gets reused in successive times leading the app to misteriously crash