diff options
Diffstat (limited to 'doc/coding_standards.txt')
| -rw-r--r-- | doc/coding_standards.txt | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/doc/coding_standards.txt b/doc/coding_standards.txt new file mode 100644 index 0000000..1a9b52e --- /dev/null +++ b/doc/coding_standards.txt @@ -0,0 +1,118 @@ +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 ``flags_variable`` +global private variable ``__flags_variable`` +global macro ``_FLAGS_SOME_MACRO_`` +public function ``flags_function`` +public function, local variable ``flags_variable_`` +private function ``_flags_function`` +private function, local variable ``_flags_variable_`` +================================ ======================== + +Where it makes sense to improve readability, variables can have the first +letter of the second and later words capitalized. For example, the local +variable name for the help string length is ``flags_helpStrLen_``. + +There are three special-case global public variables used. They are used due to +overcome the limitations of shell scoping or to prevent forking. The three variables are: + + - flags_error + - flags_output + - flags_return + +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$ |