aboutsummaryrefslogtreecommitdiffstats
path: root/notes/coding_standard.txt
diff options
context:
space:
mode:
Diffstat (limited to 'notes/coding_standard.txt')
-rw-r--r--notes/coding_standard.txt164
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))))