add admintools

doc/.svn/pristine/27/27390dedceb17119ed5174fe0b955586fb59fdbe.svn-base

@@ -0,0 +1,111 @@
+Coding Standards
+================
+
+shFlags is more than just a simple 20 line shell script. It is a pretty
+significant library of shell code that at first glance is not that easy to
+understand. To improve code readability and usability, some guidelines have
+been set down to make the code more understandable for anyone who wants to read
+or modify it.
+
+Function Documentation
+----------------------
+
+Each function should be preceded by a header that provides the following:
+
+#. A one-sentence summary of what the function does
+#. (optional) A longer description of what the function does, and perhaps some
+   special information that helps convey its usage better.
+#. Args: a one-line summary of each argument of the form:
+   ``name: type: description``
+#. Output: a one-line summary of the output provided. Only output to STDOUT
+   must be documented, unless the output to STDERR is of significance (i.e. not
+   just an error message). The output should be of the form:
+   ``type: description``
+#. Returns: a one-line summary of the value returned. Returns in shell are
+   always integers, but if the output is a true/false for success (i.e. a
+   boolean), it should be noted. The output should be of the form:
+   ``type: description``
+
+Here is a sample header: ::
+
+  # Return valid getopt options using currently defined list of long options.
+  #
+  # This function builds a proper getopt option string for short (and long)
+  # options, using the current list of long options for reference.
+  #
+  # Args:
+  #   _flags_optStr: integer: option string type (__FLAGS_OPTSTR_*)
+  # Output:
+  #   string: generated option string for getopt
+  # Returns:
+  #   boolean: success of operation (always returns True)
+
+Variable and Function Names
+---------------------------
+
+All shFlags specific constants, variables, and functions will be prefixed
+appropriately with 'flags'. This is to distinguish usage in the shFlags 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 built-in constants and variables will be surrouned with squiggle
+brackets, e.g. '${flags_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            ``FLAGS_TRUE``
+global private constant           ``__FLAGS_SHELL_FLAGS``
+global public variable            not used
+global private variable           ``__flags_someVariable``
+global macro                      ``_FLAGS_SOME_MACRO_``
+public function                   ``assertEquals``
+public function, local variable   ``flags_someVariable_``
+private function                  ``_flags_someFunction``
+private function, local variable  ``_flags_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 ``flags_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, and 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
+
+When a conditional expression is written using the builtin [ command, and that
+line must be wrapped, place the control || or && operators on the same line as
+the expression where possible, with the list to be executed on its own line. ::
+
+  [ -n 'some really long expression' -a -n 'some other long expr' ] && \
+      echo 'that was actually true!'
+
+.. vim:spell
+.. $Id$