Code Recommended Practices

From Hero of Allacrost Wiki
Revision as of 16:33, 21 July 2015 by Roots (talk | contribs) (Documentation Recommendations)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page lists recommended practices to make your code more readable, more consistent, faster, and less prone to errors and other technical issues. While these recommendations are not a part of the code standard, you'd best heed these recommendations as if they were. Failing to ignore these recommendations will often lead someone to come along and make your code conform to these guidelines.

General Recommendations[edit]

  • Follow the same code style as the surrounding code
  • Before making large design changes, post about your intentions on the forums first to get feedback/approval
  • Don't use '!' in comparison operations. Instead use if (status == false), which is easier to read and less likely to cause errors
  • Use the PRINT macros for errors, warnings, and debug messages (PRINT_DEBUG, IF_PRINT_WARNING, etc.)
  • Don't use magic numbers like if (tile_count == 256). Declare and use constants instead

Technical Recommendations[edit]

  • Prefer using pre-incrementer (++i) over post-incrementer (i++)
  • In a header/file source pair, make the order in which classes and functions are declared in the header match the order in which they are defined in the source
  • Manually enumerate Lua tables because by default they begin counting at index 1, not 0
  • Always check the return value of any 'Load*' functions
  • #include defs.h instead of making class declarations in your files
  • Don't use the using namespace directive in header files, but do use them in source files

Documentation Recommendations[edit]

  • Add a comment at the end of long code blocks (more than can be shown in a single screen) to indicate what the end bracket corresponds to.
  • Add "\todo" or "// TODO:" comments as necessary to note future work or changes that are needed
  • Only comment on the implementation details in source files. Don't bother with explaining functions that are already documented in header files
  • Add a comment when you need to blatantly violate an article of the code standard or ignore a recommendation
  • Wrap large numbers of similar function declarations into a doxygen group to reduce repetitive commenting