Changes between Version 3 and Version 4 of CodingTips


Ignore:
Timestamp:
2017-09-11T11:49:25Z (8 years ago)
Author:
Jiri Svoboda
Comment:

Add mandatory and recommended coding practices

Legend:

Unmodified
Added
Removed
Modified

  • CodingTips

    v3 v4  
    11= Coding Tips =
     2
     3== Mandatory coding practices ==
     4
     5These are absolutely required for any contribution.
     6
     7 * Adhere to the [wiki:CStyle coding style standard]
     8 * Document your code
     9    * Doxygen and regular comments
     10 * Adhere to RCS rules from the very beginnning
     11    * Use Bazaar for revision control
     12    * Separate into reasonably-sized changesets
     13    * Changeset comments must be complete, descriptive English sentences, typically in infinitive/imperative tense
     14{{{
     15Example: Fix DNS resolution not working due to missing local address.
     16}}}
     17
     18== Recommended coding practices ==
     19
     20Good coding practices that are highly recommended (but cannot be mandatory, since they're not necessarily measurable).
     21
     22 * Principle of least surprise
     23    * Comments are good, but code should be self-explanatory
     24    * Optimize code for understandability
     25 * Separation of concerns, divide et impera
     26    * Separate code into small modules, functions with well-defined interfaces ([https://www.youtube.com/watch?v=heh4OeB9A-c 1])
     27 * Unit testing
     28    * Design for testability ([https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H 2])
     29    * Every non-trivial module should have carefully written unit tests (PCUT)
     30
     31== Resources on Good Coding Practices ==
     32
     33 * 1. [https://www.youtube.com/watch?v=heh4OeB9A-c How To Design A Good API and Why it Matters (video)]
     34 * 2. [https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H Design Tech Talk Series Presents: OO Design for Testability (video)]
    235
    336== Preprocessor defines, macros, inline functions ==
    … …  
    942 * Prefer using regular functions to static inline functions
    1043  * Practically never needed, it is just premature optimization
    11 
    12 == Other Resources on Good Coding Practices ==
    13 
    14  * [https://www.youtube.com/watch?v=heh4OeB9A-c How To Design A Good API and Why it Matters (video)]
    15  * [https://www.youtube.com/watch?v=acjvKJiOvXw&list=PLvqMob1eOxGIW51K9PA_N4u2MJbddNw-H Design Tech Talk Series Presents: OO Design for Testability (video)]