diff --git a/HACKING.md b/CONTRIBUTING.md similarity index 82% rename from HACKING.md rename to CONTRIBUTING.md index dcbdfd34f..d80477cee 100644 --- a/HACKING.md +++ b/CONTRIBUTING.md @@ -1,43 +1,70 @@ + +# Contributing to Proxmark3 + +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: + +This guide covers mostly coding style for submitting pull requests, but you can also contribute by [Reporting Bugs](https://github.com/RfidResearchGroup/proxmark3/issues) and [Suggesting Enhancements](https://github.com/RfidResearchGroup/proxmark3/issues) after having carefully checked that a corresponding issue doesn't exist yet. + +Beware we're all very busy so the best way is by providing yourself some fixes and enhancements via [Pull Requests](https://github.com/RfidResearchGroup/proxmark3/pulls) respecting the following coding style. + +[Styleguides](#styleguides) + * [Overview](#overview) + * [Indentation](#indentation) + * [Width](#width) + * [Macros](#macros) + * [Identifiers](#identifiers) + * [Data types](#data-types) + * [Expressions](#expressions) + * [If / for / while etc](#if-for-while-etc) + * [Functions](#fonctions) + * [Structs / unions / enums](#structs-unions-enums) + * [Switch](#switch) + * [Comments](#comments) + * [File](#file) + * [File headers](#file-headers) + * [Header files](#header-files) + * [Whitespace](#whitespace) + +# Styleguides + _"Coding styles are like assholes, everyone has one and no one likes anyone elses."_ --Eric Warmenhoven -# Overview +## Overview -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 +We have established a set of coding style guidelines in order to clean up the code consistently and keep it consistent in the future. Look around and respect the same style. Helper script to get some uniformity in the style: -`$ make style` +```bash +$ make style +``` It makes use of `astyle` so be sure to install it first. -# Indentation +## Indentation Don't use tabs, editors are messing them up too easily. Increment unit is four spaces. If you use `make style`, this will be done for you. -# Width +## 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 +## Macros `#define`, function-like or not, are all UPPERCASE unless you're emulating a well-known function name. -# Identifiers +## Identifiers Functions, local variables, and arguments are all named using `underscores_as_spaces`. Global variables are Evil and are prepended with `g_` to @@ -49,7 +76,7 @@ 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 +## 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 @@ -57,39 +84,39 @@ 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 and reference operators are attached to the variable name: -``` +```c void *ptr; ``` not: -``` +```c void* ptr; ``` otherwise you're tempted to write: -``` +```c void* in, out; ``` and you'll fail. `make style` will take care of pointers & reference operators. -# Expressions +## Expressions In general, use whitespace around binary operators - no unspaced blobs of an expression. `make style` will take care of whitespaces around operators. For example, -``` +```c if (5 * a < b && some_bool_var) ``` but not -``` +```c if (5*a= 0x7f) return '.'; @@ -155,7 +182,7 @@ static int ascii(char c) { } ``` vs. -``` +```c static void hexdump(void *buf, size_t len) { ... } @@ -164,10 +191,10 @@ 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 +## Structs / unions / enums Use typedefs when defining structs. The type should be named something_t. -``` +```c typedef struct { blah blah; } prox_cmd_t; @@ -175,10 +202,10 @@ typedef struct { You can use anonymous enums to replace lots of sequential or mostly-sequential #defines. -# Switch +## Switch Indent once for the `case:` labels, then again for the body. Like this: -``` +```c switch(bar) { case OPTION_A: do_stuff(); @@ -199,7 +226,7 @@ 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: -``` +```c switch(bar) { case OPTION_A: { int baz = 5 * bar; @@ -210,10 +237,10 @@ switch(bar) { ``` But at that point you should probably consider using a separate function. -# Comments +## Comments Use //, it's shorter: -``` +```c // this does foo ... @@ -225,7 +252,7 @@ Use //, it's shorter: 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 +## 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 @@ -234,10 +261,10 @@ 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 +## File headers License/description header first: -``` +```c //----------------------------------------------------------------------------- // YOUR COPYRIGHT LINE GOES HERE // @@ -251,10 +278,10 @@ License/description header first: If you modify a file in any non-trivial way (add code, etc.), add your copyright to the top with the current year. -# Header files +## Header files Use the following include guard format: -``` +```c #ifndef FOOBAR_H__ #define FOOBAR_H__ @@ -265,7 +292,7 @@ Use the following include guard format: Keep in mind that `__FOOBAR_H` would be reserved by the implementation and thus you shouldn't use it (same for `_FOOBAR_H`). -# Whitespace +## Whitespace Avoid trailing whitespace (no line should end in tab or space). Keep a newline (blank line) at the end of each file.