added notes/coding_standard.txt, more cleanups

1 files changed, 164 insertions, 0 deletions

diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
new file mode 100644
index 0000000..bab1e38
--- /dev/null
+++ b/notes/coding_standard.txt
@@ -0,0 +1,164 @@
+Source code standards for libmaple.
+
+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.
+
+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
+will provide you additional help.
+
+Vim customizations to do the same thing would be nice!
+
+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
+  LeafLabs LLC.
+
+  Emacs: if you don't like seeing the license, you should use
+  elide-head (which will hide it for you).  Here is some elisp you can
+  modify to make this pleasant:
+
+    (require 'elide-head)
+    (setq programming-mode-hooks '(c-mode-hook c++-mode-hook))
+    (add-to-list 'elide-head-headers-to-hide
+                 '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE"))
+    (add-to-list 'elide-head-headers-to-hide
+                 '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE"))
+    (dolist (hook mbolivar-programming-mode-hooks)
+      (add-hook hook (lambda () (elide-head))))
+
+Whitespace
+----------
+
+- 4 space indents.  [Set in .dir-locals.el]
+
+- Unix newlines.
+
+- No tab characters. [Set in .dir-locals.el]
+
+- No trailing whitespace.  For help getting this (and no tab
+  characters) done automatically in Emacs, you can use this:
+
+    http://github.com/mbolivar/code-fascism
+
+  I hear tell you can get something similar in vim; ask Perry, 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.
+
+- The first line in a function is non-blank.
+
+Comments
+--------
+
+- Multi-line comments look like this:
+
+    /* text starts here
+     * continued lines have a '*' before them
+     * the comment can end after the last line
+     */
+
+  or this:
+
+    /* comment starts here
+     * the comment can end on the same line */
+
+- Doxygen comments are newline comments that begin with /** instead.
+
+- Single-line comments on the same line are // in c or c++.
+
+- Single-line comments on their own source line are /* */ in c, but
+  can also be // in c++.  If you think that typing out /* */ is too
+  slow in emacs, use M-; (comment-dwim) when you're on an empty line,
+  and it'll ... well...
+
+      You should be using the (super awesome) comment-dwim; it pretty
+      much does exactly what you want to the comment on the current
+      line, including "create one and put it in the right place".
+
+Braces
+------
+
+- 1TBS.  Nothing more need be said.
+
+      http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS
+
+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?
+
+- Variables: Use underscores to separate words in C identifiers:
+
+    int some_example_name;
+
+  It is strongly advised to do it this way in C++ too, but it's not
+  [yet] mandatory.
+
+- Classes: Pascal case.  So ThisIsAClassName, but thisIsNot,
+  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.
+
+- 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.
+
+- Acronyms: The case of letters in an acronym is determined by the
+  case of the first letter in the acronym.  Examples:
+
+      void usb_func() { ... }
+
+      class SomethingUSB {
+          void usbInit();
+          void initUSB();
+      };
+
+  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!
+
+- At least put a doxygen comment with a nonempty @brief for every
+  source file you add.  See the existing ones for examples.
+
+General Formatting
+------------------
+
+- Keep it 80-column clean.  That means Emacs says the largest column
+  number=79.  If you haven't already, you should turn on column
+  numbers to help you out:
+
+    (column-number-mode 1)
+
+  You can get more help from lineker-mode.  Download it here:
+
+    http://www.helsinki.fi/~sjpaavol/programs/lineker.el
+
+  Then put the file somewhere in your load-path, and
+
+    (require 'lineker)
+    (dolist (hook programming-mode-hooks)
+      (add-hook hook (lambda () (lineker-mode 1))))