X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fmanual%2Fstyle.txt;h=54c1342e64d47165cb60d990574b2b67cef06518;hp=c6dc3ca2531276219b6eca67d0673a5e15bef5ba;hb=c3beb69c476ac1faa163e70e1ab091654c6902a6;hpb=8ab9b6d39eb2f17e7367b48855736ae73ad8360f diff --git a/doc/manual/style.txt b/doc/manual/style.txt index c6dc3ca253..54c1342e64 100644 --- a/doc/manual/style.txt +++ b/doc/manual/style.txt @@ -49,7 +49,7 @@ OpenOCD project. - 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: @@ -66,8 +66,9 @@ 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). @@ -76,9 +77,19 @@ Finally, try to avoid lines of code that are longer than than 72-80 columns: - 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 + - if size matters, use the types from \ or \: + - @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 + - do @b NOT redefine @c uN types from "types.h" @section stylefunc Functions @@ -99,6 +110,20 @@ int f(int x1, int x2) int y = f(x1, x2 - x1); ... } +@endcode +- Separate assignment and logical test statements. In other words, you +should write statements like the following: +@code +// separate statements should be preferred +result = foo(); +if (ERROR_OK != result) + ... +@endcode +More directly, do @b not combine these kinds of statements: +@code +// Combined statements should be avoided +if (ERROR_OK != (result = foo())) + return result; @endcode */ @@ -128,7 +153,7 @@ comments. * in blocks such as the one in which this example appears in the Style * Guide. See the Doxygen Manual for the full list of commands. * - * @param foo For a function, describe the parameters (e.g. @a foo). + * @param foo For a function, describe the parameters (e.g. @a foo). * @returns The value(s) returned, or possible error conditions. */ @endverbatim @@ -155,7 +180,7 @@ The following guidelines apply to all Doxygen comment blocks: -# @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: @@ -208,7 +233,7 @@ This file contains the @ref pagename page. @endverbatim For an example, the Doxygen source for this Style Guide can be found in -@c doc/manual/style.txt, alongside other parts of The Manual. +@c doc/manual/style.txt, alongside other parts of The Manual. */ /** @page styletexinfo Texinfo Style Guide @@ -283,7 +308,7 @@ For technical reference material: - 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. @@ -323,7 +348,7 @@ Likewise, the @ref primerlatex for using this guide needs to be completed. This page provides some style guidelines for using Perl, a scripting language used by several small tools in the tree: --# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and +-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and @c .pm for modules) -# Pass files as script parameters or piped as input: - Do NOT code paths to files in the tree, as this breaks out-of-tree builds. @@ -337,17 +362,15 @@ perl script.pl Maintainers must also be sure to follow additional guidelines: -# Ensure that Perl scripts are committed as executables: - - Use "chmod +x script.pl" - @a before using "svn add script.pl", or - - Use "svn ps svn:executable '*' script.pl" - @a after using "svn add script.pl". + Use "chmod +x script.pl" + @a before using "git add script.pl" */ /** @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.