- 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.
-
-Finally, try to avoid lines of code that are longer than than 72-80 columns:
+- 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:
- long lines frequently indicate other style problems:
- insufficient use of static functions, macros, or temporary variables
- 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
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 prefered over macros:
+- 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
-# @c struct_name::member_name should be used to reference structure
fields in the documentation (e.g. @c flash_driver::name).
-# URLS get converted to markup automatically, without any extra effort.
- -# new pages can be linked into the heirarchy by using the @c \@subpage
+ -# new pages can be linked into the hierarchy by using the @c \@subpage
command somewhere the page(s) under which they should be linked:
-# use @c \@ref in other contexts to create links to pages and sections.
-# Use good Doxygen mark-up:
- Doxygen creates such pages for files automatically, but no content
will appear on them for those that only contain manual pages.
- The \@file block should provide useful meta-documentation to assist
- techincal writers; typically, a list of the pages that it contains.
+ technical writers; typically, a list of the pages that it contains.
- For example, the @ref styleguide exists in @c doc/manual/style.txt,
which contains a reference back to itself.
-# The \@file and \@page commands should begin on the same line as
is a guide for how and why to use each feature or mechanism of OpenOCD.
It is also the reference manual for all commands and options involved
in using them, including interface, flash, target, and other drivers.
-At this time, it is the only user-targetted documentation; everything
+At this time, it is the only documentation for end users; everything
else is addressing OpenOCD developers.
There are two key audiences for the User's Guide, both developer based.
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
projects / fw / openocd / blobdiff