diff options
| -rw-r--r-- | doc/manual/style.txt | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/doc/manual/style.txt b/doc/manual/style.txt new file mode 100644 index 00000000..f6b6f639 --- /dev/null +++ b/doc/manual/style.txt @@ -0,0 +1,93 @@ +/** @page styleguide OpenOCD Coding C Style Guide + +The following rules describe a formatting, naming, and other conventions +that should be followed when writing or changing the OpenOCD C code. +Many of the general rules should apply to OpenOCD's Jim/TCL code as well. + +The goals of this guide are: +- to produce code that appears clean, consistent, and readable, +- to allow developers to create patches that conform to a standard, +- to eliminate these issues as points of future contention. +consistent. + +Some of these rules may be ignored in the spirit of these stated goals; +however, such exceptions should be fairly rare. + +@section styleformat Formatting Rules + +- remove any trailing white space at the end of lines. +- use TAB characters for indentation; do NOT use spaces. +- displayed TAB width is 4 characters. +- use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n') +- limit adjacent empty lines to at most two (2). +- remove any trailing empty lines at the end of source files +- do not "comment out" code from the tree; instead, one should either: + -# remove it entirely (Subversion can retrieve the old version), or + -# use an @c #if/#endif block. + +Finally, try to avoid lines of code that are longer than than 72-80 columns: + +- long lines frequently indicate other style problems: + - insufficient use of static functions, macros, or temporary variables + - poor flow-control structure; "inverted" logical tests +- a few lines may be wider than this limit (typically format strings), but: + - all C compilers will concatenate series of string constants. + - all long string constants should be split across multiple lines. + +@section stylenames Naming Rules + +- most identifiers must use lower-case letters (and digits) only. + - macros must use upper-case letters (and digits) only. + - OpenOCD identifiers should NEVER use @c MixedCaps. +- structure names must end with the '_s' suffix. +- typedef names must end with the '_t' suffix. +- use underline characters between consecutive words in identifiers + (e.g. @c more_than_one_word). + +@section stylec99 C99 Rules + +- inline functions +- @c // comments -- in new code, prefer these for single-line comments +- trailing comma allowed in enum declarations +- designated initializers (@{ .field = value @}) +- variables declarations may be mixed with code +- new block scopes for selection and iteration statements + +@section stylefunc Functions + +- static inline functions should be prefered over macros: +@code +/** do NOT define macro-like functions like this... */ +#define CUBE(x) ((x) * (x) * (x)) +/** instead, define the same expression using a C99 inline function */ +static inline int cube(int x) { return x * x * x; } +@endcode +- Functions should be declared static unless required by other modules + - define static functions before first usage to avoid forward declarations. +- Functions should have no space between its name and its parameter list: +@code +int f(int x1, int x2) +{ + ... + int y = f(x1, x2 - x1); + ... +} +@endcode + +@section styledoxygen Doxygen Rules + +- use @c /// to for one-line documentation +- for multiple lines, use a "block" style with one space +@verbatim +/** + * @brief Short description. + * Full description here. + * @param foo Describe foo. + */ +@endverbatim +- if the total line length will be less than 72 columns, then + - The @c /**< form can be used on the same line. + - This style should be used sparingly; the best use is for fields: + - @code int field /**< field description */ @endcode + + */ |