From 7b72956308b7793defc6bf708ea4dc830573c0a6 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 27 Sep 2010 03:47:47 -0400 Subject: added notes/coding_standard.txt, more cleanups --- notes/coding_standard.txt | 164 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 notes/coding_standard.txt (limited to 'notes') 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)))) -- cgit v1.2.3