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))))