105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
# Style Guide for DOFS
|
|
Coding style matters a lot. Good coding styles makes the code look
|
|
better to the eye, and can help mitigate some pitfalls and confusions.
|
|
|
|
## Sane Defaults
|
|
When editing C/C++ code, it is preferred to use the following `astyle`
|
|
configuration (please consider to put it in your `.astylerc`):
|
|
|
|
```
|
|
--style=java -k3 -W3 -m0 -f -p -H --squeeze-lines=3 -xb -xf -xh -c --max-code-length=80 -xL -Y --indent=spaces=8
|
|
```
|
|
|
|
## Indentation
|
|
For all indentation, use **spaces**, not tabs.
|
|
|
|
The rationale behind this is to avoid different indent width settings
|
|
in different editors. It's a great trade-off of making your source
|
|
file a little bigger for portability to different editors.
|
|
|
|
### C/C++
|
|
Use 8 spaces. This is not only to adhere to the Linux kernel's coding
|
|
style, but also to prevent your indentation levels from getting too
|
|
big.
|
|
|
|
**IMPORTANT: If the indentation is blowing lines off the 80-char
|
|
width, you should probably consider refactoring the logic.**
|
|
|
|
### Python
|
|
Use 4 spaces. This is enough for scripts, and a choice by the people
|
|
behind python.
|
|
|
|
### Shell scripts
|
|
Use 4 spaces. There might be arguments to make it 2, but 4 is the
|
|
minimum if you want to spot something appearing in an incorrect level
|
|
when you've been staring at the screen for 15 hours.
|
|
|
|
### Line width
|
|
80 characters is preferred, but it can be extended by 20 characters or
|
|
so to accommodate longer identifiers.
|
|
|
|
If it breaches 80 characters, consider breaking it into multiple lines.
|
|
|
|
However, it is important to note that when passing many
|
|
parameters/logic, it should always be broken into logical chunks for
|
|
each line.
|
|
|
|
## Avoid magic numbers
|
|
Unless it's the bit-length of a byte or something that's commonly
|
|
known and obvious at first glance, use a constant to store it.
|
|
|
|
## Arrays
|
|
Avoid using arrays that are more than 2 dimensions. If you need to
|
|
store multiple dimensions of data, consider using `struct` or
|
|
different containers to clarify what each dimension stores.
|
|
|
|
## Naming schemes
|
|
Names are only meaningful to humans, and the rationale behind the
|
|
following guidelines is to allow anyone reading the code to know what
|
|
an identifier refers to without scrolling back to its definition or
|
|
other references.
|
|
|
|
### Snake case or camel case?
|
|
Snake case for functions and variables' names, use camel case for
|
|
class/type/enum names.
|
|
|
|
### Scoping
|
|
For all identifiers, it's important to note the scope of their usage.
|
|
Names are there to avoid confusion, not add to them, and the
|
|
considerations about confusion should fall in the same scope as their
|
|
usage.
|
|
|
|
### Abbreviating
|
|
Using abbreviations is okay and a good idea under the right
|
|
circumstances.
|
|
|
|
As a general rule of thumb, the aggressiveness of abbreviating words
|
|
is inversely proportional to the size of the scope. But it's a **bad
|
|
idea** to abbreviate global identifiers that are not commonly used.
|
|
|
|
### Constants
|
|
For all constants and enums, use **ALL_CAPS**.
|
|
|
|
### Global identifiers
|
|
Use **FULL NAMES** unless it's something pre-agreed on or by
|
|
specifications like `mosi` or `sys_clk`.
|
|
|
|
## Commenting
|
|
Comments are great, but don't over-comment, they are there
|
|
for exactly two things:
|
|
|
|
1. Tell people **what** the code does
|
|
2. Give a signal for future development (e.g. implementation notes,
|
|
usage warnings, required guarantees)
|
|
|
|
If you need to explain how your code does something using comments,
|
|
it's a better idea to re-write the code.
|
|
|
|
## Output Messages
|
|
Like comment signals, messages should also be in complete lines and
|
|
`grep`-friendly.
|
|
|
|
## Tricks and workarounds
|
|
Don't try to write "smart" code, instead, write code that everyone can
|
|
understand without too much explanation.
|