aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--notes/coding_standard.txt102
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
+ ...
+ ))