forked from Proxmark/proxmark3
-
Notifications
You must be signed in to change notification settings - Fork 2
/
HACKING.txt
291 lines (209 loc) · 7.81 KB
/
HACKING.txt
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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
"Coding styles are like assholes, everyone has one and no one likes anyone elses."
--Eric Warmenhoven
The Proxmark3 codebase is pretty messy and in the process of being cleaned up,
so we don't have clear guidelines on how to place new code just yet. However,
please don't make things worse.
However, we have established a set of coding style guidelines in order to
clean up the code consistently and keep it consistent in the future. Use common
sense and good taste. If breaking a rule leads to cleaner code, you can do so,
but laziness is not an excuse.
=== INDENTATION ===
Use tabs for indentation, but use spaces for alignment:
if (foo(this, that, there)
&& bar == baz)
{
dostuff();
}
Notice it's like this (T___ for tab, S for space, for a 4-char tab setting):
T___if (foo(this, that, there)
T___SSSS&& bar == baz)
Another example:
#define THIS 0x10
#define THAT_THING 0x20
#define SOMETHING_ELSE 0x80
These should look good no matter what your editor's tab setting is, so go nuts
and pick whatever you like best.
=== WIDTH ===
Try to keep lines to a reasonable length. 80 characters is a good mark; using an
editor that shows a vertical line is a great idea. However, don't break a line
just because you're slightly over, it's not worth it. No 200-character lines,
though.
=== MACROS ===
#defines, function-like or not, are all UPPERCASE unless you're emulating a
well-known function name.
=== IDENTIFIERS ===
Functions, local variables, and arguments are all named using
underscores_as_spaces. Global variables are Evil and are prepended with g_ to
distinguish them. Avoid them.
Single-character variables are a bad idea. Exceptions: loop iterators and maybe
simple byte pointers (*p) in very obvious places. If you have more than one
such pointer, use a real name. If you have more than a couple nested loops,
complex logic, or indices that differ in interpretation or purpose, use real
names instead of i,j,k.
=== DATA TYPES ===
Use stdint.h types (uint32_t and friends) unless you have a reason not to. Don't
use microsoft-style DWORD and the like, we're getting rid of those. Avoid char
for buffers, uint8_t is more obvious when you're not working with strings. Use
'const' where things are const. Try to use size_t for sizes.
Pointers are:
void *ptr;
not:
void* ptr;
otherwise you're tempted to write:
void* in, out;
and you'll fail.
=== EXPRESSIONS ===
In general, use whitespace around binary operators - no unspaced blobs of an
expression. This rule may be broken if it makes things clearer. For example,
if (5*a < b && some_bool_var)
but not
if (5*a<b&&some_bool_var)
For equality with constants, use i == 0xF00, not 0xF00 == i. The compiler warns
you about = vs == anyway, and you shouldn't be screwing that one up by now
anyway.
=== IF / FOR / WHILE / etc. ===
Put the opening brace on the same line, with a space before it. Exception: if
the if/for/while condition/whatever are split over several lines, it might be
more appealing to put the opening brace on its own line, so use your own
judgement there:
if (foo(this, that, there)
&& bar == baz)
{
dostuff();
}
If you do split the condition, put the binary operators that join the lines at
the beginning of the following lines (as above), not at the end of the prior
lines.
There should be a space between the construct name (if/for/whatever) and the
opening parenthesis, and there should be a space between the closing parenthesis
and the opening brace.
For generic for() iterator variables, declare them in-line:
for (int i = 0; i < 10; i++) {
...
}
Note the spaces after the semicolons.
if/else should be laid out as follows:
if (foo) {
...
} else if (bar) {
...
} else {
...
}
or
if (foo)
...
else if (bar)
...
else
...
Don't mix braces vs. no braces. If any of your bodies are > 1 line, put braces
around them all.
=== FUNCTIONS ===
Functions with no arguments are declared as f(void), not f(). Put the return
type on the same line. Use static for functions that aren't exported, and put
exported functions in a header file (one header file per source file with
exported functions usually, no huge headers with all functions). Put a space
after a comma in argument lists.
void foo(int a_thing, int something_else)
{
...
}
void baz(void)
{
foo(bluh, blah);
}
Function names should be separated_with_underscores(), except for standard
functions (memcpy, etc.). It may make sense to break this rule for very common,
generic functions that look like library functions (e.g. dprintf()).
Don't use single-character arguments. Exception: very short functions with one
argument that's really obvious:
static int ascii(char c)
{
if (c < 0x20 || c >= 0x7f)
return '.';
else
return c;
}
vs.
static void hexdump(void *buf, size_t len)
{
...
}
As a general guideline, functions shouldn't usually be much more than 30-50
lines. Above, the general algorithm won't be easily apparent, and you're
probably missing some factoring/restructuring opportunity.
=== STRUCTS / UNIONS / ENUMS ===
Use typedefs when defining structs. The type should be named something_t.
typedef struct {
blah blah;
} prox_cmd_t;
You can use anonymous enums to replace lots of sequential or mostly-sequential
#defines.
=== SWITCH ===
Indent once for the case: labels, then again for the body. Like this:
switch(bar) {
case OPTION_A:
do_stuff();
break;
case OPTION_B:
do_other_stuff();
break;
}
If you fall through into another case, add an explicit comment; otherwise, it
can look confusing.
If your switch() is too long or has too many cases, it should be cleaned up.
Split off the cases into functions, break the switch() into parent and children
switches (e.g. command and subcommand), or use an array of function pointers or
the like. In other words, use common sense and your brain.
If you need local scope variables for a case, you can add braces:
switch(bar) {
case OPTION_A: {
int baz = 5*bar;
do_stuff(baz);
break;
}
...
But at that point you should probably consider using a separate function.
=== COMMENTS ===
Use //, it's shorter:
// this does foo
...
// baz:
// This does blah blah blah .....
// blah blah...
/* */ can be used to comment blocks of code, but you should probably remove
them anyway - we have version control, it's easy to fetch old code if needed,
so avoid committing commented out chunks of code. The same goes for #if 0.
=== FILE ===
Please use common sense and restrain yourself from having a thousands+++ line
file. Functions in a file should have something *specific* in common. Over time
sub-categories can arise and should therefore yield to file splitting.
For these reasons, vague and general filenames (e.g. util.*, global.*, misc.*,
main.*, and the like) should be very limited, if not prohibited.
=== FILE HEADERS ===
License/description header first:
//-----------------------------------------------------------------------------
// YOUR COPYRIGHT LINE GOES HERE
//
// This code is licensed to you under the terms of the GNU GPL, version 2 or,
// at your option, any later version. See the LICENSE.txt file for the text of
// the license.
//-----------------------------------------------------------------------------
// FILE DESCRIPTION GOES HERE
//-----------------------------------------------------------------------------
If you modify a file in any non-trivial way (add code, etc.), add your copyright
to the top.
=== HEADER FILES ===
Use the following include guard format:
#ifndef FOOBAR_H__
#define FOOBAR_H__
...
#endif // FOOBAR_H__
Keep in mind that __FOOBAR_H would be reserved by the implementation and thus
you shouldn't use it (same for _FOOBAR_H).
=== WHITESPACE ===
Avoid trailing whitespace (no line should end in tab or space). People forget
this all the time if their editor doesn't handle it, but don't be surprised if
you see someone fixing it from time to time.
Keep a newline (blank line) at the end of each file.