From 4fc25350c21d9a18beeed5cc9d6db78c2a0cac0d Mon Sep 17 00:00:00 2001 From: marcansoft Date: Sun, 21 Feb 2010 19:16:36 +0000 Subject: [PATCH] Add HACKING.txt with coding style guidelines --- HACKING.txt | 278 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 HACKING.txt diff --git a/HACKING.txt b/HACKING.txt new file mode 100644 index 000000000..f2fb1a8a6 --- /dev/null +++ b/HACKING.txt @@ -0,0 +1,278 @@ + 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 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) +{ + ... +} + +=== 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 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.