= Coding Guidelines =

== 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 Git for revision control
    * Separate into reasonably-sized changesets
    * Make sure that each commit is accompanied by a commit message that follows the example below. The first line should be a short description of WHAT the commit does written in imperative mood. It should not exceed 50 columns of text width and the trailing period should be omitted. The next line should be empty. Optionally, you may provide additional paragraphs that explain WHY the change was made. The text should not exceed 72 columns of width. Note that some editors will help you follow these rules by text highlighting. The entire commit message must be written in English.
{{{
Make INTERFACE_LOC_SUPPLIER parallel
    
Location service sometimes needs to be able to process requests in
parallel in order to avoid deadlock.
}}} 

 * Unit testing
    * All non-trivial newly added code should have carefully written unit tests (PCUT)
    * Ideally develop tests in parallel with the actual code
    * Design for testability ([https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H 2])

== 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])

== 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