wiki:MtglProgrammingStandards

Coding Standards for the MTGL

The easy way to follow these standards is to run your code through uncrustify using the config file found at doc/uncrustify.cfg. There are a couple of things it does wrong:

  • Multiline typedefs are indented wrong.
  • Variable declarations where the variable name is on a second line are indented wrong.

What it doesn't do:

  • Change indentation on pragmas.

Formatting

  • Indentation is two spaces.
  • Always use spaces and never tabs.
  • Typenames in templates should be UpperCamelCase.
  • Preprocessor macros should be UPPER_CASE_SEPARATED_BY_UNDERSCORES.
  • All other names should generally be lower_case_separated_by_underscores.
  • No line should exceed 80 characters in width.
  • Pragma statements should be indented to the level of the code they modify. All other preprocessor macros should start in column 1.
  • Opening braces should always be put on a line by themselves indented to the same level as the element they follow. The one exception to this is opening braces for structures and objects should be put on the same line as the preceding statement.
    for (int i = 0; i < arr_size; ++i)
    {
      int val = arr[i];
      // Do something with val.
    }
    
    struct my_pair {
      int first;
      int second;
    };
    
  • One line for, if, etc. statements are allowed (and encouraged as long as they don't exceed the 80 character limit). For these, don't use braces and put a single space after the closing parenthesis.
    for (int i = 0; i < arr_size; ++i) sum += arr[i];
    
  • Except for one-liners, all for, if, etc. statements should use braces.
    for (int i = 0; i < arr_size; ++i)
    {
      sum += arr[i];
    }
    
  • Only define one variable per line.
  • The '&' and '*' for references and pointers should be placed next to the type, not the variable.
    int* var = 0;
    

Other

  • Always use pre-increment unless you need the value before the increment. This is a good rule of thumb for all C++ programming. Post-increment is more expensive than pre-increment for objects (aka iterators).
  • Always include a header guard in library files. It should be "MTGL_" followed by the name of the file, but replacing the period with an underscore. For instance, euler_tour.hpp should be MTGL_EULER_TOUR_HPP.
  • Always undef macros in library files at the bottom of the file they were defined in, unless they should be available for users of the library.
  • Use proper English in comments. Among other things, capitalize the first word of every sentence, and use punctuation correctly. Sentence fragments are acceptable, but still capitalize the first word and put a period at the end.
  • All objects, functions, etc. that are not part of the public interface should be in the namespace mtgl::detail. This includes all helper objects and functions.
  • Library code should never print out anything unless it is an error.
  • Debugging output should be enclosed in an "#ifdef DEBUG ... #endif" pair.