=======================
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/