diff options
Diffstat (limited to 'notes')
| -rw-r--r-- | notes/coding_standard.txt | 37 |
1 files changed, 23 insertions, 14 deletions
diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt index 0e250d5..5cb96c3 100644 --- a/notes/coding_standard.txt +++ b/notes/coding_standard.txt @@ -60,7 +60,7 @@ Whitespace/Indentation - Files end in exactly one newline. [The presence of a newline at EOF is already done by `c-require-final-newline' in recent versions of - emacs.] + Emacs.] - Exactly two newlines separate source paragraphs (you do separate your code into paragraphs, don't you?). @@ -140,9 +140,8 @@ Naming conventions - Structs: pick a style from "Variables" or "Classes" depending on how you mean it (since it might be either a simple record type, in which case do like c variables, or you might be faking an object in c, in - which case do like classes). If it's in a typedef, should also - probably put _t at the end, but maybe you won't, and I don't really - feel too strongly about it. + which case do like classes). If it's in a typedef, don't feel + obliged to put "_t" at the end of the name; we don't. - Macros and constants: all caps, separated by underscores. Variables with the "const" qualifier aren't considered "constants" for the @@ -169,7 +168,7 @@ Naming conventions Documentation ------------- -- Document your code! +- Document your code. This should go without saying. - For complicated peripherals, it would be nice if you put longer-form comments into this directory (notes/), with a comment in the @@ -185,6 +184,21 @@ Documentation michaeljones breathe repos on github and potentially figure out why). +- Doxygen comments generally just belong on types, functions, + etc. that are part of the public user-facing API. This generally + means that if there's ReST documentation for it under docs/source/, + it needs Doxygen comments, and that ReST should use Breathe to pull + that Doxygen comment out. (For more info on this, see docs/README). + + There are some exceptions to this rule since Breathe isn't totally + mature yet and Sphinx's C++ domain is still in flux. In these + cases, document the code "manually" in ReST. + + This should be avoided if at all possible, since it creates a + maintenance burden of documenting things in two places at once, and + provides an opportunity for bad documentation to slip in, when the + code comments fall out of sync with the ReST docs. + General Formatting ------------------ @@ -201,14 +215,9 @@ General Formatting Then put the file somewhere in your load-path, and: (require 'lineker) - (dolist (hook programming-mode-hooks) + (dolist (hook '(c-mode-hook c++-mode-hook)) (add-hook hook (lambda () (lineker-mode 1)))) - Where "programming-mode-hooks" is a list that should at least - include c-mode-hook and c++-mode-hook; e.g.: - - (setq programming-mode-hooks '(c-mode-hook - c++-mode-hook - python-mode-hook - ... - )) + There are only a few exceptional situations. The most important one + is when specifying a lookup table like PIN_MAP where it'd be ugly to + split each entry over multiple lines. |