doc/manual/style.txt

   1 /** @page styleguide OpenOCD Coding C Style Guide
   2
   3 The following rules describe a formatting, naming, and other conventions
   4 that should be followed when writing or changing the OpenOCD C code.
   5 Many of the general rules should apply to OpenOCD's Jim/TCL code as well.
   6
   7 The goals of this guide are:
   8 - to produce code that appears clean, consistent, and readable,
   9 - to allow developers to create patches that conform to a standard,
  10 - to eliminate these issues as points of future contention.
  11 consistent.
  12
  13 Some of these rules may be ignored in the spirit of these stated goals;
  14 however, such exceptions should be fairly rare.
  15
  16 @section styleformat Formatting Rules
  17
  18 - remove any trailing white space at the end of lines.
  19 - use TAB characters for indentation; do NOT use spaces.
  20 - displayed TAB width is 4 characters.
  21 - use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n')
  22 - limit adjacent empty lines to at most two (2).
  23 - remove any trailing empty lines at the end of source files
  24 - do not "comment out" code from the tree; instead, one should either:
  25   -# remove it entirely (Subversion can retrieve the old version), or
  26   -# use an @c #if/#endif block.
  27
  28 Finally, try to avoid lines of code that are longer than than 72-80 columns:
  29
  30 - long lines frequently indicate other style problems:
  31   - insufficient use of static functions, macros, or temporary variables
  32   - poor flow-control structure; "inverted" logical tests
  33 - a few lines may be wider than this limit (typically format strings), but:
  34   - all C compilers will concatenate series of string constants.
  35   - all long string constants should be split across multiple lines.
  36
  37 @section stylenames Naming Rules
  38
  39 - most identifiers must use lower-case letters (and digits) only.
  40   - macros must use upper-case letters (and digits) only.
  41   - OpenOCD identifiers should NEVER use @c MixedCaps.
  42 - structure names must end with the '_s' suffix.
  43 - typedef names must end with the '_t' suffix.
  44 - use underline characters between consecutive words in identifiers
  45   (e.g. @c more_than_one_word).
  46
  47 @section stylec99 C99 Rules
  48
  49 - inline functions
  50 - @c // comments -- in new code, prefer these for single-line comments
  51 - trailing comma allowed in enum declarations
  52 - designated initializers (@{ .field = value @})
  53 - variables declarations may be mixed with code
  54 - new block scopes for selection and iteration statements
  55
  56 @section stylefunc Functions
  57
  58 - static inline functions should be prefered over macros:
  59 @code
  60 /** do NOT define macro-like functions like this... */
  61 #define CUBE(x) ((x) * (x) * (x))
  62 /** instead, define the same expression using a C99 inline function */
  63 static inline int cube(int x) { return x * x * x; }
  64 @endcode
  65 - Functions should be declared static unless required by other modules
  66   - define static functions before first usage to avoid forward declarations.
  67 - Functions should have no space between its name and its parameter list:
  68 @code
  69 int f(int x1, int x2)
  70 {
  71         ...
  72         int y = f(x1, x2 - x1);
  73         ...
  74 }
  75 @endcode
  76
  77 @section styledoxygen Doxygen Rules
  78
  79 - use @c /// to for one-line documentation
  80 - for multiple lines, use a "block" style with one space
  81 @verbatim
  82 /**
  83  * @brief Short description.
  84  * Full description here.
  85  * @param foo Describe foo.
  86  */
  87 @endverbatim
  88 - if the total line length will be less than 72 columns, then
  89   - The @c /**< form can be used on the same line.
  90   - This style should be used sparingly; the best use is for fields:
  91     - @code int field /**< field description */ @endcode
  92
  93  */