You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
59 lines
4.4 KiB
59 lines
4.4 KiB
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
|
|
spiInterfaceDriver.h.
|
|
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, beginning 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 the 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 will warn you if you accidentally try to dereference it, or on purpose 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
|
|
substantial.
|
|
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.
|