blob: ea40c45c9e4673af6a0bef5ebba6c740fab70374 [file] [log] [blame]
In the interest of a clean and concise codebase that looks readable, it is hereby established that the code will follow these guidelines.
Finding an example that does not obey these guidelines is not a cause for also disobeying them (it is a cause for fixing it, however)
0. Code will not be wrapped to 80 characters. We all have 24+ inch high-res displays. Let's use them.
That being said, this is not an endorsement of 500-character lines. Be reasonable.
1. File names shall be camel case and descriptive. Keep them short too. Eg: spi.h is better than
2. All function names shall be camel-case, beginning with a lowercase letter.
3. All functions that are visibile in the global scope (outside their C file) shall begin with the
name of their module (gpio, pwm, os)
4. All functions not visible in the global scope shall be declared static
5. Functions taking no parameters shall be declated as (void) and not as ()
6. All type names shall be camel-case, beginnign with a capital letter.
7. All types in the global scope shall begin with their module name. (GpioPullType, SpiDeviceHandle)
8. There should be *NO* globally-visible variables. All non-stack variables shall be declared
"static" and reside in one C file
9. All global variables in a given C file shall begin with "m" and then be in camel case. This is to
make it easier to identify them
10. All variables shall be declared in the beginning of the block where they reside. This facilitates
easily looking over code and estimating memory use
11. typedef is forbidden except for function pointer types. Do not typedef structs or unions. Use full
names - makes it easy to appreciate the cost (struct GpioHandle, union PwmDeviceData)
12. Do not use short. char is allowed for actual printable strings only. Use uint8_t/uint16_t/
uint32_t/uint64_t for clarity of intentions and clear delineation of size needed.
13. int/unsigned int is allowed only for simple loop iterators only (or, if you must, as a return type
when you wish to return more than one error class). Do not assume ints are 32 bits. Or 64. Or 16.
14. Do not use uint16_t/uint8_t for function parameters/return types. Gcc generates very bad code for
those cases and you will lose. However, uint8_t/uint16_t are ok to use in structs/unions
15. All structures shall be packed to avoid space waste, as compiler is not allowed to pack them for
you. If you are not sure how to, sort members by size (uint64_t members first, then uint32_t
members, etc)
16. Do not ever return structs or unions from functions. Pass a pointer and fill it in. Gcc will
optimize this better and it is better C
17. All definitions/defines/structs/unions that are only used by one source file belong in that C
file. There is never a need for "myModule_priv.h" unless the module is made of a few C files
18. Absolutely no "double" types are allowed. Absolutely no passing of "float" vars through var-args
(it converts to double)
19. Absolutely no inline assembly unless you're in a folder under "cpu" or "variant". Allowed in
"platform" only if platform only supports one CPU type
20. You may use whatever comment style suits your heart, as long as the compiler can live with it
21. You may not change compiler flags in order to remove warnings or errors. They are there for a
reason, listen to them and fix the code instead.
22. Whenever possible, hide struct definitions from global scope. Eg: gpio funcs return
"struct Gpio*". Actual struct Gpio definition is not public. Not only does this help with clean
code, it wil lwarn you if you accidentally try to derefernce it, or on purpiose try to access
internal private state. Also this allows platform-independence to continue.
23. commit messages shall begin with module they touch and a colon, eg "spi: fix spi-dma on stm64"
24. Do not divide 64-bit values. If you simply must, only do so by a constant, and use cpuMath.h.
This will be enforced at compile time and will fail your build. This is intentional as the power
and speed costs are substantial.
25. Do not cast floats to 64-bit values or back, this is slow. Use floatRt.h. This will be enforced
at compile time and will fail your build. This is intentional as the power and speed costs are
26. Do not use types with uncertain sizes. NO size_t, ssize_t, etc. use uintXX_t or uintptr_t
99. These guidelines will be kept updated as things come up/are decided