added README and some other documentation

style.md

@@ -0,0 +1,104 @@
+# 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.