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.
 
 
 
 
 
 

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