Updated coding standard

1 files changed, 76 insertions, 26 deletions

diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
index bab1e38..0e250d5 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.txt
@@ -1,21 +1,31 @@
-Source code standards for libmaple.
+libmaple Coding Standards
+=========================
 
-Do it like this unless there's a really good reason why not.  You
-being a lazy bastard doesn't count as a good reason.
+Author: Marti Bolivar (mbolivar@leaflabs.com)
+
+LeafLabs team members are required to follow these when producing new
+code.  Community contributors to libmaple are strongly encouraged to
+do so; following these rules will greatly increase the probability
+that your patches will be folded in.
+
+In general, do it like this unless there's a really good reason why
+not.  You being lazy doesn't count as a good reason.  Most, if not
+all, of these decisions are entirely arbitrary, but it's important for
+readability that we be consistent.
 
 The file .dir-locals.el in the libmaple root directory already ensures
-that many of these standards are followed by default, if you use emacs
-(and not Windows, where it would need to be named _dir_locals.el, and
-no way, man).  There's also some elisp scattered about this file which
+that many of these standards are followed by default in Emacs (but not
+on Windows, where it would need to be named _dir_locals.el, and no
+way, man).  There's also some elisp scattered about this file which
 will provide you additional help.
 
-Vim customizations to do the same thing would be nice!
+Vim customizations to do the same thing would be nice (hint, hint)!
 
 License
 -------
 
 - Put an MIT license at the beginning of the file (look at any of our
-  source files for an example).  Copyright should go to either your or
+  source files for an example).  Copyright should go to either you or
   LeafLabs LLC.
 
   Emacs: if you don't like seeing the license, you should use
@@ -31,8 +41,8 @@ License
     (dolist (hook mbolivar-programming-mode-hooks)
       (add-hook hook (lambda () (elide-head))))
 
-Whitespace
-----------
+Whitespace/Indentation
+----------------------
 
 - 4 space indents.  [Set in .dir-locals.el]
 
@@ -45,17 +55,28 @@ Whitespace
 
     http://github.com/mbolivar/code-fascism
 
-  I hear tell you can get something similar in vim; ask Perry, I
+  I hear tell you can get something similar in vim; ask around, I
   guess.
 
 - 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.]
 
-- Exactly two newlines separate source paragraphs.
+- Exactly two newlines separate source paragraphs (you do separate
+  your code into paragraphs, don't you?).
 
 - The first line in a function is non-blank.
 
+- Don't indent C code within a conditionally-compiled extern "C"
+  block.  Emacs does this by default, which can be very annoying; you
+  can turn this behavior off with
+
+        (defun c-mode-inextern-lang-hook ()
+          (setcdr (assq 'inextern-lang c-offsets-alist) '-))
+
+        (add-hook 'c-mode-hook c-mode-inextern-lang-hook)
+
+
 Comments
 --------
 
@@ -72,6 +93,7 @@ Comments
      * the comment can end on the same line */
 
 - Doxygen comments are newline comments that begin with /** instead.
+  It is not required that the "/**" appear on a line by itself.
 
 - Single-line comments on the same line are // in c or c++.
 
@@ -94,9 +116,13 @@ Braces
 Naming conventions
 ------------------
 
-So there's always a fight about upper and lower case vs. underscores.
-We'll handle this as follows.  First, Dammit_Dont_Mix_Like_This,
-because It_Looks_Really_Ugly, ok?
+- There's always a fight about upper and lower case vs. underscores.
+  We'll handle this as follows.
+
+  First, Dammit_Dont_Mix_Like_This, because It_Looks_Really_Ugly, ok?
+  [There's been some debate about this, and some exceptions are
+  already grandfathered in, so in order to settle it, let's call this
+  a "recommendation" instead of "requirement".]
 
 - Variables: Use underscores to separate words in C identifiers:
 
@@ -109,7 +135,7 @@ because It_Looks_Really_Ugly, ok?
   this_is_not, and like I said, Dont_You_DareTryANYTHING_STUPID.
 
 - Functions: C functions are all lowercase, and words are separated by
-  underscores.  C++ method names are camel cased.
+  underscores.  C++ method names are camel cased (thisIsAnExample).
 
 - 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
@@ -118,8 +144,16 @@ because It_Looks_Really_Ugly, ok?
   probably put _t at the end, but maybe you won't, and I don't really
   feel too strongly about it.
 
+- Macros and constants: all caps, separated by underscores.  Variables
+  with the "const" qualifier aren't considered "constants" for the
+  purposes of this rule; i.e., case them according to the rules for
+  variables.
+
+- foo.h gets #ifdef'ed to _FOO_H_.
+
 - Acronyms: The case of letters in an acronym is determined by the
-  case of the first letter in the acronym.  Examples:
+  case of the first letter in the acronym, which is determined by
+  following the above rules.  Examples:
 
       void usb_func() { ... }
 
@@ -128,21 +162,28 @@ because It_Looks_Really_Ugly, ok?
           void initUSB();
       };
 
-  NEVER DO THIS:
+  Never do this:
 
       class BadUsb { ... }; // say "GoodUSB" instead
 
-- Macros and constants: all caps, separated by underscores.
-
-- foo.h gets ifdef'ed to _FOO_H_.
-
 Documentation
 -------------
 
-- Document your code, bitches!
+- Document your code!
 
-- At least put a doxygen comment with a nonempty @brief for every
-  source file you add.  See the existing ones for examples.
+- For complicated peripherals, it would be nice if you put longer-form
+  comments into this directory (notes/), with a comment in the
+  corresponding .h file referring to it.  See libmaple/dac.h for an
+  example.  That lets us keep the source files relatively clean while
+  still allowing new readers to have a starting point.
+
+- At least put a doxygen comment with a nonempty @brief for every .h
+  file you add.  See the existing ones for examples.  For now, it'd be
+  better if you didn't put a @brief into any .c[pp] files, since it
+  (currently) interferes with our documentation generator in a way
+  that I won't explain here (though you can look into the LeafLabs or
+  michaeljones breathe repos on github and potentially figure out
+  why).
 
 General Formatting
 ------------------
@@ -157,8 +198,17 @@ General Formatting
 
     http://www.helsinki.fi/~sjpaavol/programs/lineker.el
 
-  Then put the file somewhere in your load-path, and
+  Then put the file somewhere in your load-path, and:
 
     (require 'lineker)
     (dolist (hook programming-mode-hooks)
       (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
+                                   ...
+                                   ))