Difference between revisions of "Coding Style (OpenXcom)"
Jump to navigation
Jump to search
(Created page with "== Naming == * In general, CamelCase, with words only separated by uppercases. * ClassNames start with an uppercase. * anyOther variable or method starts with a lowercase. * _pri...") |
m |
||
Line 29: | Line 29: | ||
* Methods should have a one-sentence brief description (///) in their header declaration and a multi-line full description (/**) in their definition. | * 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. | * Don't forget to document method parameters and return values. | ||
− | * Write in proper English. Please. | + | * 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. | * 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. | * Remember Doxygen will warn you about errors / missing documentation so run it from time to time. | ||
− | == Misc == | + | == Misc. == |
* In general, OOP conventions apply. | * 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. | * Keep each class in its own equally-named header/source file. Keeping related enums/structs in the same file is fine. |
Revision as of 15:06, 16 November 2011
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 [i]inevitably[/i] 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!