Coding Style (OpenXcom)

From UFOpaedia
Jump to: navigation, search

Naming

  • In general, CamelCase, with words only separated by uppercases.
  • ClassNames start with an uppercase.
  • anyOther variable or method starts with a lowercase.
  • _privateMembers start with an underscore.
  • DEFINES_ENUMS_CONSTANTS are all uppercase with words separated by underscores.

Spacing

  • In general, space things like you were writing a sentence. Don't let the code get squished up (eg. "a = 5 * b(4, 3) + -3 / 80" vs "a=5*b(4,3)+-3/80").
  • Spaces after commas, semicolons, variables, operators, etc.
  • No need for spaces after opening parenthesis.
  • Use linebreaks to keep large unrelated blocks of code separate.
  • Use tabs for indenting code blocks between brackets, one tab per level.

Readability

  • Keep names nice and readable, specially if they're public, remember there's auto-complete. Abbreviations are ok occasionally.
  • Short names are ok if it's just a minor variable or you'll be writing it a lot (eg. iterators called i, j, k).
  • Use static consts for "magic numbers" that are hard to figure out on their own. Don't go replacing 0 with ZERO, but don't go leaving something like 8443.90438 either.
  • Keep long operations intact if it improves readability, the compiler will automatically calculate them anyways. (eg. "margin = (60 + 2 * 12 + 25) / 2)" vs "margin = 54.5").
  • Use comments to explain long boring code blocks.
  • Use // for comments even if they're multi-line, it keeps them from getting in the way when you comment out code blocks with /* */.
  • Split a comment into multiple lines if it gets too long. Same should apply to code, although I don't do it much.
  • Avoid copy-pasting, avoid incredibly long code blocks, use spacing and comments and even more functions to keep everything neat.
  • Keep the code clean, no useless includes, declarations, etc.

Documentation

  • Doxygen is used for OpenXcom, with the convention of /// for single-line documentation, /** for multi-line documentation and @ for attributes (@param, @return, etc).
  • Classes should have a multi-line description of their purpose in their header declaration.
  • Methods should have a one-sentence brief description (///) in their header declaration and a multi-line full description (/**) in their definition.
  • Don't forget to document method parameters and return values.
  • Write in proper English. Please.
  • Always end your sentences with a dot. This is usually not relevant for comments, but I think Doxygen uses these to better tidy up the stuff.
  • Remember Doxygen will warn you about errors / missing documentation so run it from time to time.

Misc.

  • In general, OOP conventions apply.
  • Keep each class in its own equally-named header/source file. Keeping related enums/structs in the same file is fine.
  • Always use brackets to start a block, even if it's just one line. Yes yes I know it's so many space wasted for one line, but eventually inevitably you'll slip up and forget to add them when you extend it. I know I have.
  • Opening/closing brackets always lined up in their own lines.
  • Keep variable declarations where relevant, don't leave them all at the start of code blocks ala ANSI-C, it makes it harder to tell their purpose.
  • When declaring pointers, keep the * on the side of the variable name. This prevents common mistakes like "int* a, b, c" (only a will be a pointer).
  • Feel free to put multiple declarations in one line.
  • No need to check for null pointers when deleting stuff.
  • Don't use NULL, it's not actually in the C++ standard and will be later replaced with nullptr by C++0x.
  • Use iterators for looping through STL containers (vectors, maps, etc.).
  • Use pre-increment/decrement (++i and --i) instead of post-increment/decrement (i++ and i--) except when it produces a different result.
  • Use const on methods that don't change its class (eg. getter methods).
  • Don't pass objects to functions by copy, use pointers or references (eg. "const std::string &s" instead of just "std::string s").
  • Remember the C++ standard requires an empty linebreak on the end of every file.
  • Avoid making generic utility classes or functions, keep everything in the class it's relevant to (make more classes if you have to, can never have enough!).
  • Use common sense!