Add HACKING.txt with coding style guidelines

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<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)
+{
+	...
+}
+
+=== 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.