RfidResearchGroup/proxmark3
1
1
Fork 0
mirror of https://github.com/RfidResearchGroup/proxmark3.git synced 2025-02-28 10:05:13 +08:00
Code Issues Projects Releases Packages Wiki Activity

hacking.txt -> .md + ref in readme

Browse source
This commit is contained in:
Philippe Teuwen 2019-05-05 00:41:20 +02:00
parent bfed6602b8
commit fa82f24517
2 changed files with 89 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

165
HACKING.txt → HACKING.md
View file

@ -1,5 +1,7 @@
"Coding styles are like assholes, everyone has one and no one likes anyone elses."
--Eric Warmenhoven
_"Coding styles are like assholes, everyone has one and no one likes anyone elses."_
--Eric Warmenhoven
# 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,
@ -8,99 +10,106 @@ 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.
Look around and respect the same style.
Helper script to get some uniformity in the style:
$ make style
`$ make style`
It makes use of "astyle" so be sure to install it first.
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.
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
#defines, function-like or not, are all UPPERCASE unless you're emulating a
`#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
`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
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 ===
# 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.
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 and reference operators are attached to the variable name:
```
void *ptr;
```
not:
```
void* ptr;
```
otherwise you're tempted to write:
```
void* in, out;
```
and you'll fail.
"make style" will take care of pointers & reference operators.
`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.
expression. `make style` will take care of whitespaces around operators.
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
```
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. ===
# If / for / while etc
Put the opening brace on the same line, with a space before it.
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, and no space between parenthesis and expression.
"make style" will take care of all that.
`make style` will take care of all that.
If you do split the condition, put the binary operators that join the lines at
the beginning of the following lines, not at the end of the prior lines.
For generic for() iterator variables, declare them in-line:
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) {
@ -108,68 +117,68 @@ if/else should be laid out as follows:
} else {
...
}
```
You can skip braces around 1-line statements but don't mix braces vs. no braces.
You can skip braces around 1 line statements but don't mix braces vs. no braces.
=== FUNCTIONS ===
# Functions
Put the return type on the same line.
Put a space after a comma in argument lists.
Open the brace after the declaration (after a space).
"make style" will take care of all that.
`make style` will take care of all that.
```
void foo(int a_thing, int something_else) {
...
}
Functions with no arguments are declared as f(void), not f().
```
Functions with no arguments are declared as `f(void)`, not `f()`.
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).
```
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()).
```
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 ===
# 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
Indent once for the `case:` labels, then again for the body. Like this:
```
switch(bar) {
case OPTION_A:
do_stuff();
@ -178,19 +187,19 @@ switch(bar) {
do_other_stuff();
break;
}
"make style" will take care of the indentation.
```
`make style` will take care of the indentation.
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.
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;
@ -198,37 +207,37 @@ switch(bar) {
break;
}
...
```
But at that point you should probably consider using a separate function.
=== COMMENTS ===
# 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
```
`/* */` 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.
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
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.
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:
```
//-----------------------------------------------------------------------------
// YOUR COPYRIGHT LINE GOES HERE
//
@ -238,27 +247,27 @@ License/description header first:
//-----------------------------------------------------------------------------
// FILE DESCRIPTION GOES HERE
//-----------------------------------------------------------------------------
```
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:
```
#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`).
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.
"make style" will take care of both.
`make style` will take care of both.

2
README.md
View file

@ -43,6 +43,8 @@ This fork now compiles just fine on
- ParrotOS
- WSL (Windows subsystem linux) on Windows 10
- Docker container
If you intend to contribute to the code, please read the [coding style notes](HACKING.md) first.
---
## Why didn't you base it on official PM3 Master?
The separation from official pm3 repo gives us a lot of freedom to create a firmware/client that suits the RDV40 features. We don't want to mess up the official pm3 repo with RDV40 specific code.