Coding Standards
================

Variable and Function Names
---------------------------

All shUnit2 specific constants, variables, and functions will be prefixed
appropriately with 'shunit'. This is to distinguish usage in the shUnit2 code
from users own scripts so that the shell name space remains predictable to
users. The exceptions here are the standard ``assertEquals``, etc. functions.

All non-builtin constants and variables will be surrouned with squiggle
brackets, e.g. '${shunit_someVariable}' to improve code readability.

Due to some shells not supporting local variables in functions, care in the
naming and use of variables, both public and private, is very important.
Accidental overriding of the variables can occur easily if care is not taken as
all variables are technically global variables in some shells.

+----------------------------------+---------------------------+
| *type*                           | *sample*                  |
+==================================+===========================+
| global public constant           | ``SHUNIT_TRUE``           |
+----------------------------------+---------------------------+
| global private constant          | ``__SHUNIT_SHELL_FLAGS``  |
+----------------------------------+---------------------------+
| global public variable           | not used                  |
+----------------------------------+---------------------------+
| global private variable          | ``__shunit_someVariable`` |
+----------------------------------+---------------------------+
| global macro                     | ``_SHUNIT_SOME_MACRO_``   |
+----------------------------------+---------------------------+
| public function                  | ``assertEquals``          |
+----------------------------------+---------------------------+
| public function, local variable  | ``shunit_someVariable_``  |
+----------------------------------+---------------------------+
| private function                 | ``_shunit_someFunction``  |
+----------------------------------+---------------------------+
| private function, local variable | ``_shunit_someVariable_`` |
+----------------------------------+---------------------------+

Where it makes sense, variables can have the first letter of the second and
later words capitalized. For example, the local variable name for the total
number of test cases seen might be ``shunit_totalTestsSeen_``.

Local Variable Cleanup
----------------------

As many shells do not support local variables, no support for cleanup of
variables is present either. As such, all variables local to a function must be
cleared up with the ``unset`` command at the end of each function.

Indentation
-----------

Code block indentation is two (2) spaces, and tabs may not be used. ::

  if [ -z 'some string' ]; then
    someFunction
  fi

Lines of code should be no longer than 80 characters unless absolutely
necessary. When lines are wrapped using the backslash character '\', subsequent
lines should be indented with four (4) spaces so as to differentiate from the
standard spacing of two characters. Tabs may *not* be used. ::

  for x in some set of very long set of arguments that make for a very long \
      that extends much too long for one line
  do
    echo ${x}
  done

.. vim:fileencoding=latin1:ft=rst:spell:tw=80
.. $Revision$
