- 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
+ -# 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:
- 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.
+- @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.
- use underline characters between consecutive words in identifiers
(e.g. @c more_than_one_word).
+@section style_include_guards Include Guards
+
+Every header file should have a unique include guard to prevent multiple
+inclusion.
+To guarantee uniqueness, an include guard should be based on the filename and
+the full path in the project source tree.
+
+For the header file src/helper/jim-nvp.h, the include guard would look like
+this:
+
+@code
+#ifndef OPENOCD_HELPER_JIM_NVP_H
+#define OPENOCD_HELPER_JIM_NVP_H
+
+/* Your code here. */
+
+#endif /* OPENOCD_HELPER_JIM_NVP_H */
+@endcode
+
@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
+- designated initializers ( .field = value )
+- variables declarations should occur at the point of first use
- new block scopes for selection and iteration statements
+- use malloc() to create dynamic arrays. Do @b not use @c alloca
+or variable length arrays on the stack. non-MMU hosts(uClinux) and
+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
* @returns The value(s) returned, or possible error conditions.
*/
@endverbatim
- -# The block should start on the line following the opening @c /**.
- -# The end of the block, \f$*/\f$, should also be on its own line.
+ -# The block should start on the line following the opening @c /\**.
+ -# The end of the block, @c *‍/, should also be on its own line.
-# Every line in the block should have a @c '*' in-line with its start:
- - A leading space is required to align the @c '*' with the @c /** line.
+ - A leading space is required to align the @c '*' with the @c /\** line.
- A single "empty" line should separate the function documentation
from the block of parameter and return value descriptions.
- Except to separate paragraphs of documentation, other extra
-# @c function_name() can be used to reference functions
(e.g. flash_set_dirty()).
-# @c struct_name::member_name should be used to reference structure
- fields in the documentation (e.g. @c flash_driver_s::name).
+ 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
command somewhere the page(s) under which they should be linked:
- Else it's a "Config Command" if it must be used before the
configuration stage completes.
- For a "Driver", list its name.
- - Use BNF style regular expressions to define parameters:
+ - Use EBNF style regular expressions to define parameters:
brackets around zero-or-one choices, parentheses around
exactly-one choices.
- Use \@option, \@file, \@var and other mechanisms where appropriate.
Maintainers must also be sure to follow additional guidelines:
-# Ensure that Perl scripts are committed as executables:
- - Use "<code>chmod +x script.pl</code>"
- @a before using "<code>svn add script.pl</code>", or
- - Use "<code>svn ps svn:executable '*' script.pl</code>"
- @a after using "<code>svn add script.pl</code>".
+ Use "<code>chmod +x script.pl</code>"
+ @a before using "<code>git add script.pl</code>"
*/
/** @page styleautotools Autotools Style Guide
This page contains style guidelines for the OpenOCD autotools scripts.
-The following guidelines apply to the @c configure.in file:
+The following guidelines apply to the @c configure.ac file:
- Better guidelines need to be developed, but until then...
- Use good judgement.