Added CONTRIB document

1 files changed, 92 insertions, 0 deletions

diff --git a/CONTRIB.rst b/CONTRIB.rst
new file mode 100644
index 0000000..f8da31c
--- /dev/null
+++ b/CONTRIB.rst
@@ -0,0 +1,92 @@
+=======================
+Contribution Guidelines
+=======================
+
+This is a short document describing the preferred coding style for this project
+
+
+Indentation
+===========
+
+Indentation is two spaces.
+
+While some, if not most people may disagree with this (Linus, I'm looking at
+you), this is the current standard for this project. Some standards deviating
+from will have little impact, but deviating from this standard will be quite
+noticeable, so please adhere to it.
+
+If you particularly disagree with it enough, please contact the project owner
+and they (I) might be persuaded to change it to 4 spaces (but never tabs).
+
+Rationale: If you notice the 'Line Width' section, you will see that lines are
+to be no more than 80 characters wide (though there are exceptions). Having a
+4, 8, or even greater character indentiation might increase readability from an
+indentation perspective, but will decrease readability as lines are
+unecessarily broken because not enough space remains on the line after said
+indentation.
+
+
+However, if you find your indentations don't leave you enough space with an 80
+character width, refer to this quote from Linus Torvalds.
+
+
+  Now, some people will claim that having 8-character *[or 2 in our case]*
+  indentations makes the code move too far to the right, and makes it hard to
+  read on a 80-character terminal screen.  The answer to that is that if you need
+  more than 3 levels of indentation, you're screwed anyway, and should fix your
+  program.
+
+
+
+Trailing Whitespace
+===================
+
+...is never acceptable. Most IDEs warn you about this, git warns you about
+this, I'm warning you about this. Heed the warnings.
+
+
+Functions
+=========
+
+Functions should be defined using the POSIX standard style. They should look
+like...
+
+**Example**::
+
+  foo() {
+    printf "Hello World\n"
+  }
+
+
+Rationale: This program has the possibility of running on devices that do not
+have bash installed. Having non-POSIX compliant function definitions will
+likely reduce the number of devices this script can run on, as most devices
+only come with the ash or dash shells.
+
+
+Variables inside of functions need to be scope locally.
+
+**Example**::
+
+  foo() {
+    local arg=${1}
+    local matey=${2}
+  
+    printf "Hello World\n"
+  }
+
+Having variables scoped locally will reduce the likelyhood of overwriting the
+same named variable that exists outside of the function.
+
+
+POSIX Compliance
+================
+
+Always do your best to stay within the `POSIX shell scripting standards`_. As
+unfortunate and limiting as this is, most Android devices come only with shells
+that implement the minimum to be POSIX compliant. Any scripting code that
+exceeds the POSIX standards will likely break compatibility with a number of
+devices (if not all devices).
+
+.. _POSIX shell scripting standards: http://pubs.opengroup.org/onlinepubs/9699919799/
+