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

• 1. ​How To Design A Good API and Why it Matters (video)
• 2. ​Design Tech Talk Series Presents: OO Design for Testability (video)

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