You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

423 lines
17 KiB

  1. /** @page styleguide Style Guides
  2. The goals for each of these guides are:
  3. - to produce correct code that appears clean, consistent, and readable,
  4. - to allow developers to create patches that conform to a standard, and
  5. - to eliminate these issues as points of future contention.
  6. Some of these rules may be ignored in the spirit of these stated goals;
  7. however, such exceptions should be fairly rare.
  8. The following style guides describe a formatting, naming, and other
  9. conventions that should be followed when writing or changing the OpenOCD
  10. code:
  11. - @subpage styletcl
  12. - @subpage stylec
  13. - @subpage styleperl
  14. - @subpage styleautotools
  15. In addition, the following style guides provide information for
  16. providing documentation, either as part of the C code or stand-alone.
  17. - @subpage styledoxygen
  18. - @subpage styletexinfo
  19. - @subpage stylelatex
  20. Feedback would be welcome to improve the OpenOCD guidelines.
  21. */
  22. /** @page styletcl TCL Style Guide
  23. OpenOCD needs to expand its Jim/TCL Style Guide.
  24. Many of the guidelines listed on the @ref stylec page should apply to
  25. OpenOCD's Jim/TCL code as well.
  26. */
  27. /** @page stylec C Style Guide
  28. This page contains guidelines for writing new C source code for the
  29. OpenOCD project.
  30. @section styleformat Formatting Guide
  31. - remove any trailing white space at the end of lines.
  32. - use TAB characters for indentation; do NOT use spaces.
  33. - displayed TAB width is 4 characters.
  34. - use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n')
  35. - limit adjacent empty lines to at most two (2).
  36. - remove any trailing empty lines at the end of source files
  37. - do not "comment out" code from the tree; instead, one should either:
  38. -# remove it entirely (git can retrieve the old version), or
  39. -# use an @c \#if/\#endif block.
  40. Finally, try to avoid lines of code that are longer than than 72-80 columns:
  41. - long lines frequently indicate other style problems:
  42. - insufficient use of static functions, macros, or temporary variables
  43. - poor flow-control structure; "inverted" logical tests
  44. - a few lines may be wider than this limit (typically format strings), but:
  45. - all C compilers will concatenate series of string constants.
  46. - all long string constants should be split across multiple lines.
  47. @section stylenames Naming Rules
  48. - most identifiers must use lower-case letters (and digits) only.
  49. - macros must use upper-case letters (and digits) only.
  50. - OpenOCD identifiers should NEVER use @c MixedCaps.
  51. - @c typedef names must end with the '_t' suffix.
  52. - This should be reserved for types that should be passed by value.
  53. - Do @b not mix the typedef keyword with @c struct.
  54. - use underline characters between consecutive words in identifiers
  55. (e.g. @c more_than_one_word).
  56. @section style_include_guards Include Guards
  57. Every header file should have a unique include guard to prevent multiple
  58. inclusion.
  59. To guarantee uniqueness, an include guard should be based on the filename and
  60. the full path in the project source tree.
  61. For the header file src/helper/jim-nvp.h, the include guard would look like
  62. this:
  63. @code
  66. /* Your code here. */
  67. #endif /* OPENOCD_HELPER_JIM_NVP_H */
  68. @endcode
  69. @section stylec99 C99 Rules
  70. - inline functions
  71. - @c // comments -- in new code, prefer these for single-line comments
  72. - trailing comma allowed in enum declarations
  73. - designated initializers ( .field = value )
  74. - variables declarations should occur at the point of first use
  75. - new block scopes for selection and iteration statements
  76. - use malloc() to create dynamic arrays. Do @b not use @c alloca
  77. or variable length arrays on the stack. non-MMU hosts(uClinux) and
  78. pthreads require modest and predictable stack usage.
  79. @section styletypes Type Guidelines
  80. - use native types (@c int or @c unsigned) if the type is not important
  81. - if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
  82. - @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
  83. - @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
  84. - do @b NOT redefine @c uN types from "types.h"
  85. @section stylefunc Functions
  86. - static inline functions should be prefered over macros:
  87. @code
  88. /** do NOT define macro-like functions like this... */
  89. #define CUBE(x) ((x) * (x) * (x))
  90. /** instead, define the same expression using a C99 inline function */
  91. static inline int cube(int x) { return x * x * x; }
  92. @endcode
  93. - Functions should be declared static unless required by other modules
  94. - define static functions before first usage to avoid forward declarations.
  95. - Functions should have no space between its name and its parameter list:
  96. @code
  97. int f(int x1, int x2)
  98. {
  99. ...
  100. int y = f(x1, x2 - x1);
  101. ...
  102. }
  103. @endcode
  104. - Separate assignment and logical test statements. In other words, you
  105. should write statements like the following:
  106. @code
  107. // separate statements should be preferred
  108. result = foo();
  109. if (ERROR_OK != result)
  110. ...
  111. @endcode
  112. More directly, do @b not combine these kinds of statements:
  113. @code
  114. // Combined statements should be avoided
  115. if (ERROR_OK != (result = foo()))
  116. return result;
  117. @endcode
  118. */
  119. /** @page styledoxygen Doxygen Style Guide
  120. The following sections provide guidelines for OpenOCD developers
  121. who wish to write Doxygen comments in the code or this manual.
  122. For an introduction to Doxygen documentation,
  123. see the @ref primerdoxygen.
  124. @section styledoxyblocks Doxygen Block Selection
  125. Several different types of Doxygen comments can be used; often,
  126. one style will be the most appropriate for a specific context.
  127. The following guidelines provide developers with heuristics for
  128. selecting an appropriate form and writing consistent documentation
  130. -# use @c /// to for one-line documentation of instances.
  131. -# for documentation requiring multiple lines, use a "block" style:
  132. @verbatim
  133. /**
  134. * @brief First sentence is short description. Remaining text becomes
  135. * the full description block, where "empty" lines start new paragraphs.
  136. *
  137. * One can make text appear in @a italics, @b bold, @c monospace, or
  138. * in blocks such as the one in which this example appears in the Style
  139. * Guide. See the Doxygen Manual for the full list of commands.
  140. *
  141. * @param foo For a function, describe the parameters (e.g. @a foo).
  142. * @returns The value(s) returned, or possible error conditions.
  143. */
  144. @endverbatim
  145. -# The block should start on the line following the opening @c /\**.
  146. -# The end of the block, @c *&zwj;/, should also be on its own line.
  147. -# Every line in the block should have a @c '*' in-line with its start:
  148. - A leading space is required to align the @c '*' with the @c /\** line.
  149. - A single "empty" line should separate the function documentation
  150. from the block of parameter and return value descriptions.
  151. - Except to separate paragraphs of documentation, other extra
  152. "empty" lines should be removed from the block.
  153. -# Only single spaces should be used; do @b not add mid-line indentation.
  154. -# If the total line length will be less than 72-80 columns, then
  155. - The @c /**< form can be used on the same line.
  156. - This style should be used sparingly; the best use is for fields:
  157. @code int field; /**< field description */ @endcode
  158. @section styledoxyall Doxygen Style Guide
  159. The following guidelines apply to all Doxygen comment blocks:
  160. -# Use the @c '\@cmd' form for all doxygen commands (do @b not use @c '\\cmd').
  161. -# Use symbol names such that Doxygen automatically creates links:
  162. -# @c function_name() can be used to reference functions
  163. (e.g. flash_set_dirty()).
  164. -# @c struct_name::member_name should be used to reference structure
  165. fields in the documentation (e.g. @c flash_driver::name).
  166. -# URLS get converted to markup automatically, without any extra effort.
  167. -# new pages can be linked into the heirarchy by using the @c \@subpage
  168. command somewhere the page(s) under which they should be linked:
  169. -# use @c \@ref in other contexts to create links to pages and sections.
  170. -# Use good Doxygen mark-up:
  171. -# '\@a' (italics) should be used to reference parameters (e.g. <i>foo</i>).
  172. -# '\@b' (bold) should be used to emphasizing <b>single</b> words.
  173. -# '\@c' (monospace) should be used with <code>file names</code> and
  174. <code>code symbols</code>, so they appear visually distinct from
  175. surrounding text.
  176. -# To mark-up multiple words, the HTML alternatives must be used.
  177. -# Two spaces should be used when nesting lists; do @b not use '\\t' in lists.
  178. -# Code examples provided in documentation must conform to the Style Guide.
  179. @section styledoxytext Doxygen Text Inputs
  180. In addition to the guidelines in the preceding sections, the following
  181. additional style guidelines should be considered when writing
  182. documentation as part of standalone text files:
  183. -# Text files must contain Doxygen at least one comment block:
  184. -# Documentation should begin in the first column (except for nested lists).
  185. -# Do NOT use the @c '*' convention that must be used in the source code.
  186. -# Each file should contain at least one @c \@page block.
  187. -# Each new page should be listed as a \@subpage in the \@page block
  188. of the page that should serve as its parent.
  189. -# Large pages should be structure in parts using meaningful \@section
  190. and \@subsection commands.
  191. -# Include a @c \@file block at the end of each Doxygen @c .txt file to
  192. document its contents:
  193. - Doxygen creates such pages for files automatically, but no content
  194. will appear on them for those that only contain manual pages.
  195. - The \@file block should provide useful meta-documentation to assist
  196. techincal writers; typically, a list of the pages that it contains.
  197. - For example, the @ref styleguide exists in @c doc/manual/style.txt,
  198. which contains a reference back to itself.
  199. -# The \@file and \@page commands should begin on the same line as
  200. the start of the Doxygen comment:
  201. @verbatim
  202. /** @page pagename Page Title
  203. Documentation for the page.
  204. */
  205. /** @file
  206. This file contains the @ref pagename page.
  207. */
  208. @endverbatim
  209. For an example, the Doxygen source for this Style Guide can be found in
  210. @c doc/manual/style.txt, alongside other parts of The Manual.
  211. */
  212. /** @page styletexinfo Texinfo Style Guide
  213. The User's Guide is there to provide two basic kinds of information. It
  214. is a guide for how and why to use each feature or mechanism of OpenOCD.
  215. It is also the reference manual for all commands and options involved
  216. in using them, including interface, flash, target, and other drivers.
  217. At this time, it is the only user-targetted documentation; everything
  218. else is addressing OpenOCD developers.
  219. There are two key audiences for the User's Guide, both developer based.
  220. The primary audience is developers using OpenOCD as a tool in their
  221. work, or who may be starting to use it that way. A secondary audience
  222. includes developers who are supporting those users by packaging or
  223. customizing it for their hardware, installing it as part of some software
  224. distribution, or by evolving OpenOCD itself. There is some crossover
  225. between those audiences. We encourage contributions from users as the
  226. fundamental way to evolve and improve OpenOCD. In particular, creating
  227. a board or target specific configuration file is something that many
  228. users will end up doing at some point, and we like to see such files
  229. become part of the mainline release.
  230. General documentation rules to remember include:
  231. - Be concise and clear. It's work to remove those extra words and
  232. sentences, but such "noise" doesn't help readers.
  233. - Make it easy to skim and browse. "Tell what you're going to say,
  234. then say it". Help readers decide whether to dig in now, or
  235. leave it for later.
  236. - Make sure the chapters flow well. Presentations should not jump
  237. around, and should move easily from overview down to details.
  238. - Avoid using the passive voice.
  239. - Address the reader to clarify roles ("your config file", "the board you
  240. are debugging", etc.); "the user" (etc) is artificial.
  241. - Use good English grammar and spelling. Remember also that English
  242. will not be the first language for many readers. Avoid complex or
  243. idiomatic usage that could create needless barriers.
  244. - Use examples to highlight fundamental ideas and common idioms.
  245. - Don't overuse list constructs. This is not a slide presentation;
  246. prefer paragraphs.
  247. When presenting features and mechanisms of OpenOCD:
  248. - Explain key concepts before presenting commands using them.
  249. - Tie examples to common developer tasks.
  250. - When giving instructions, you can \@enumerate each step both
  251. to clearly delineate the steps, and to highlight that this is
  252. not explanatory text.
  253. - When you provide "how to use it" advice or tutorials, keep it
  254. in separate sections from the reference material.
  255. - Good indexing is something of a black art. Use \@cindex for important
  256. concepts, but don't overuse it. In particular, rely on the \@deffn
  257. indexing, and use \@cindex primarily with significant blocks of text
  258. such as \@subsection. The \@dfn of a key term may merit indexing.
  259. - Use \@xref (and \@anchor) with care. Hardcopy versions, from the PDF,
  260. must make sense without clickable links (which don't work all that well
  261. with Texinfo in any case). If you find you're using many links,
  262. read that as a symptom that the presentation may be disjointed and
  263. confusing.
  264. - Avoid font tricks like \@b, but use \@option, \@file, \@dfn, \@emph
  265. and related mechanisms where appropriate.
  266. For technical reference material:
  267. - It's OK to start sections with explanations and end them with
  268. detailed lists of the relevant commands.
  269. - Use the \@deffn style declarations to define all commands and drivers.
  270. These will automatically appear in the relevant index, and those
  271. declarations help promote consistent presentation and style.
  272. - It's a "Command" if it can be used interactively.
  273. - Else it's a "Config Command" if it must be used before the
  274. configuration stage completes.
  275. - For a "Driver", list its name.
  276. - Use EBNF style regular expressions to define parameters:
  277. brackets around zero-or-one choices, parentheses around
  278. exactly-one choices.
  279. - Use \@option, \@file, \@var and other mechanisms where appropriate.
  280. - Say what output it displays, and what value it returns to callers.
  281. - Explain clearly what the command does. Sometimes you will find
  282. that it can't be explained clearly. That usually means the command
  283. is poorly designed; replace it with something better, if you can.
  284. - Be complete: document all commands, except as part of a strategy
  285. to phase something in or out.
  286. - Be correct: review the documentation against the code, and
  287. vice versa.
  288. - Alphabetize the \@defn declarations for all commands in each
  289. section.
  290. - Keep the per-command documentation focussed on exactly what that
  291. command does, not motivation, advice, suggestions, or big examples.
  292. When commands deserve such expanded text, it belongs elsewhere.
  293. Solutions might be using a \@section explaining a cluster of related
  294. commands, or acting as a mini-tutorial.
  295. - Details for any given driver should be grouped together.
  296. The User's Guide is the first place most users will start reading,
  297. after they begin using OpenOCD. Make that investment of their time
  298. be as productive as possible. Needing to look at OpenOCD source code,
  299. to figure out how to use it is a bad sign, though it's OK to need to
  300. look at the User's guide to figure out what a config script is doing.
  301. */
  302. /** @page stylelatex LaTeX Style Guide
  303. This page needs to provide style guidelines for using LaTeX, the
  304. typesetting language used by The References for OpenOCD Hardware.
  305. Likewise, the @ref primerlatex for using this guide needs to be completed.
  306. */
  307. /** @page styleperl Perl Style Guide
  308. This page provides some style guidelines for using Perl, a scripting
  309. language used by several small tools in the tree:
  310. -# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and
  311. @c .pm for modules)
  312. -# Pass files as script parameters or piped as input:
  313. - Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
  314. - If you must, then you must also use an automake rule to create the script.
  315. -# use @c '#!/usr/bin/perl' as the first line of Perl scripts.
  316. -# always <code>use strict</code> and <code>use warnings</code>
  317. -# invoke scripts indirectly in Makefiles or other scripts:
  318. @code
  319. perl
  320. @endcode
  321. Maintainers must also be sure to follow additional guidelines:
  322. -# Ensure that Perl scripts are committed as executables:
  323. Use "<code>chmod +x</code>"
  324. @a before using "<code>git add</code>"
  325. */
  326. /** @page styleautotools Autotools Style Guide
  327. This page contains style guidelines for the OpenOCD autotools scripts.
  328. The following guidelines apply to the @c file:
  329. - Better guidelines need to be developed, but until then...
  330. - Use good judgement.
  331. The following guidelines apply to @c files:
  332. -# When assigning variables with long lists of items:
  333. -# Separate the values on each line to make the files "patch friendly":
  334. @code
  335. VAR = \
  336. value1 \
  337. value2 \
  338. ...
  339. value9 \
  340. value10
  341. @endcode
  342. */
  343. /** @file
  344. This file contains the @ref styleguide pages. The @ref styleguide pages
  345. include the following Style Guides for their respective code and
  346. documentation languages:
  347. - @ref styletcl
  348. - @ref stylec
  349. - @ref styledoxygen
  350. - @ref styletexinfo
  351. - @ref stylelatex
  352. - @ref styleperl
  353. - @ref styleautotools
  354. */