= Coding Tips =

== Mandatory coding practices ==

These are absolutely required for any contribution.

 * Adhere to the [wiki:CStyle 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 ([https://www.youtube.com/watch?v=heh4OeB9A-c 1])
 * Unit testing
    * Design for testability ([https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H 2])
    * Every non-trivial module should have carefully written unit tests (PCUT)

== Resources on Good Coding Practices ==

 * 1. [https://www.youtube.com/watch?v=heh4OeB9A-c How To Design A Good API and Why it Matters (video)]
 * 2. [https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H 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