- 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 (git can retrieve the old version), or
- -# use an @c \#if/\#endif block.
+- do not "comment out" code from the tree nor put it within a block
+ @code
+ #if 0
+ ...
+ #endif
+ @endcode
+ otherwise it would never be checked at compile time and when new
+ patches get merged it could be not compilable anymore.
+ Code that is not fully working nor ready for submission should
+ instead be removed entirely (git can retrieve the old version).
+ For exceptional cases that require keeping some unused code, let
+ the compiler check it by putting it in a block
+ @code
+ if (false) {
+ /* explain why this code should be kept here */
+ ...
+ }
+ @endcode
+- in a @c switch statement align the @c switch with the @c case label
+ @code
+ switch (dev_id) {
+ case 0x0123:
+ size = 0x10000;
+ break;
+ case 0x0412:
+ size = 0x20000;
+ break;
+ default:
+ size = 0x40000;
+ break;
+ }
+ @endcode
+- in an <tt> if / then / else </tt> statement, if only one of the conditions
+ require curly brackets due to multi-statement block, put the curly brackets
+ also to the other condition
+ @code
+ if (x > 0)
+ a = 12 + x;
+ else
+ a = 24;
+ @endcode
+ @code
+ if (x > 0) {
+ a = 12 + x;
+ } else {
+ a = 24;
+ x = 0;
+ }
+ @endcode
Finally, try to avoid lines of code that are longer than 72-80 columns:
- 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.
+ - do never exceed 120 columns.
@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.
+ - macros and enumerators must use upper-case letters (and digits) only.
+ - OpenOCD identifiers should NEVER use @c MixedCaps, aka @c CamelCase.
- @c typedef names must end with the '_t' suffix.
- This should be reserved for types that should be passed by value.
- Do @b not mix the typedef keyword with @c struct.
pthreads require modest and predictable stack usage.
@section styletypes Type Guidelines
-- use native types (@c int or @c unsigned) if the type is not important
+- use native types (@c int or <tt> unsigned int </tt>) if the type is not important
- if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
- @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
- @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
+ - use the associated @c printf and @c scanf formatting strings for these types
+ (e.g. @c PRId8, PRIx16, SCNu8, ...)
- do @b NOT redefine @c uN types from "types.h"
+ - use type @c target_addr_t for target's address values
+ - prefer type <tt> unsigned int </tt> to type @c unsigned
@section stylefunc Functions
- static inline functions should be preferred over macros:
@code
-/** do NOT define macro-like functions like this... */
+/* do NOT define macro-like functions like this... */
#define CUBE(x) ((x) * (x) * (x))
-/** instead, define the same expression using a C99 inline function */
+/* 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
@code
// separate statements should be preferred
result = foo();
-if (ERROR_OK != result)
+if (result != ERROR_OK)
...
@endcode
More directly, do @b not combine these kinds of statements:
@code
// Combined statements should be avoided
-if (ERROR_OK != (result = foo()))
+if ((result = foo()) != ERROR_OK)
return result;
+@endcode
+- Do not compare @c bool values with @c true or @c false but use the
+ value directly
+@code
+if (!is_enabled)
+ ...
+@endcode
+- Avoid comparing pointers with @c NULL
+@code
+buf = malloc(buf_size);
+if (!buf) {
+ LOG_ERROR("Out of memory");
+ return ERROR_FAIL;
+}
@endcode
*/
"empty" lines should be removed from the block.
-# Only single spaces should be used; do @b not add mid-line indentation.
-# If the total line length will be less than 72-80 columns, then
- - The @c /**< form can be used on the same line.
+ - 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
+ @verbatim int field; /**< field description */ @endverbatim
@section styledoxyall Doxygen Style Guide
vice versa.
- Alphabetize the \@defn declarations for all commands in each
section.
-- Keep the per-command documentation focussed on exactly what that
+- Keep the per-command documentation focused on exactly what that
command does, not motivation, advice, suggestions, or big examples.
When commands deserve such expanded text, it belongs elsewhere.
Solutions might be using a \@section explaining a cluster of related
Code Review / openocd.git / blobdiff