1 /** @page styleguide OpenOCD Coding C Style Guide
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.
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.
13 Some of these rules may be ignored in the spirit of these stated goals;
14 however, such exceptions should be fairly rare.
16 @section styleformat Formatting Rules
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.
28 Finally, try to avoid lines of code that are longer than than 72-80 columns:
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.
37 @section stylenames Naming Rules
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).
47 @section stylec99 C99 Rules
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
56 @section stylefunc Functions
58 - static inline functions should be prefered over macros:
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; }
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:
72 int y = f(x1, x2 - x1);
77 @section styledoxygen Doxygen Rules
79 - use @c /// to for one-line documentation
80 - for multiple lines, use a "block" style with one space
83 * @brief Short description.
84 * Full description here.
85 * @param foo Describe foo.
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