1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
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 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, don't feel
obliged to put "_t" at the end of the name; we don't.
- 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. This should go without saying.
- At least put a doxygen comment with a nonempty @brief for every
source file you add. See the existing ones for examples.
- Doxygen comments generally just belong on types, functions,
etc. that are part of the public user-facing API. This generally
means that if there's ReST documentation for it under docs/source/,
it needs Doxygen comments, and that ReST should use Breathe to pull
that Doxygen comment out. (For more info on this, see docs/README).
There are some exceptions to this rule since Breathe isn't totally
mature yet and Sphinx's C++ domain is still in flux. In these
cases, document the code "manually" in ReST.
This should be avoided if at all possible, since it creates a
maintenance burden of documenting things in two places at once, and
provides an opportunity for bad documentation to slip in, when the
code comments fall out of sync with the ReST docs.
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 '(c-mode-hook c++-mode-hook))
(add-hook hook (lambda () (lineker-mode 1))))
There are only a few exceptional situations. The most important one
is when specifying a lookup table like PIN_MAP where it'd be ugly to
split each entry over multiple lines.
|
