Version 4 (modified by Jiri Svoboda, 6 years ago) ( diff )

Add mandatory and recommended coding practices

Coding Tips

Mandatory coding practices

These are absolutely required for any contribution.

  • Adhere to the coding style standard
  • Document your code
    • Doxygen and regular comments
  • Adhere to RCS rules from the very beginnning
    • Use Bazaar for revision control
    • Separate into reasonably-sized changesets
    • Changeset comments must be complete, descriptive English sentences, typically in infinitive/imperative tense
      Example: Fix DNS resolution not working due to missing local address.

Recommended coding practices

Good coding practices that are highly recommended (but cannot be mandatory, since they're not necessarily measurable).

  • Principle of least surprise
    • Comments are good, but code should be self-explanatory
    • Optimize code for understandability
  • Separation of concerns, divide et impera
    • Separate code into small modules, functions with well-defined interfaces (1)
  • Unit testing
    • Design for testability (2)
    • Every non-trivial module should have carefully written unit tests (PCUT)

Resources on Good Coding Practices

Preprocessor defines, macros, inline functions

  • Prefer using enum instead of preprocessor defines for constants
    • Preprocessor defines are only necessary when you are using the constant both in C and assembly sources
  • Prefer using static inline functions instead of preprocessor macros
    • Preprocessor macros are only needed (a) for type polymorphism, (b) if the result needs to be an l-value (R/W accessor)
  • Prefer using regular functions to static inline functions
    • Practically never needed, it is just premature optimization
Note: See TracWiki for help on using the wiki.