# 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.