aboutsummaryrefslogtreecommitdiffstats
path: root/notes
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@mit.edu>2010-12-21 10:31:01 -0500
committerMarti Bolivar <mbolivar@mit.edu>2010-12-21 10:31:01 -0500
commit61b310c5124b27226f1a6ade5cd726128fed61aa (patch)
treed2d1f8a1a533f50b1a679ed4d1bd64a4292fae77 /notes
parentc45bccad44187da27505cf5808424e709e3f54a1 (diff)
downloadlibrambutan-61b310c5124b27226f1a6ade5cd726128fed61aa.tar.gz
librambutan-61b310c5124b27226f1a6ade5cd726128fed61aa.zip
readme and coding standard updates
Diffstat (limited to 'notes')
-rw-r--r--notes/coding_standard.txt32
1 files changed, 25 insertions, 7 deletions
diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
index bab1e38..c0e4e4e 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.txt
@@ -50,7 +50,7 @@ Whitespace
- 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.
@@ -71,7 +71,7 @@ Comments
/* comment starts here
* the comment can end on the same line */
-- Doxygen comments are newline comments that begin with /** instead.
+- Doxygen comments begin with /** instead.
- Single-line comments on the same line are // in c or c++.
@@ -114,9 +114,8 @@ because It_Looks_Really_Ugly, ok?
- 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.
- Acronyms: The case of letters in an acronym is determined by the
case of the first letter in the acronym. Examples:
@@ -139,11 +138,26 @@ because It_Looks_Really_Ugly, ok?
Documentation
-------------
-- Document your code, bitches!
+- Document your code. This should go without saying.
- At least put a doxygen comment with a nonempty @brief for every
source file you add. See the existing ones for examples.
+- 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
------------------
@@ -160,5 +174,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))))
+
+ 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.