1Coding Standards 2================ 3 4shFlags is more than just a simple 20 line shell script. It is a pretty 5significant library of shell code that at first glance is not that easy to 6understand. To improve code readability and usability, some guidelines have 7been set down to make the code more understandable for anyone who wants to read 8or modify it. 9 10Function Documentation 11---------------------- 12 13Each function should be preceded by a header that provides the following: 14 15#. A one-sentence summary of what the function does 16#. (optional) A longer description of what the function does, and perhaps some 17 special information that helps convey its usage better. 18#. Args: a one-line summary of each argument of the form: 19 ``name: type: description`` 20#. Output: a one-line summary of the output provided. Only output to STDOUT 21 must be documented, unless the output to STDERR is of significance (i.e. not 22 just an error message). The output should be of the form: 23 ``type: description`` 24#. Returns: a one-line summary of the value returned. Returns in shell are 25 always integers, but if the output is a true/false for success (i.e. a 26 boolean), it should be noted. The output should be of the form: 27 ``type: description`` 28 29Here is a sample header: :: 30 31 # Return valid getopt options using currently defined list of long options. 32 # 33 # This function builds a proper getopt option string for short (and long) 34 # options, using the current list of long options for reference. 35 # 36 # Args: 37 # _flags_optStr: integer: option string type (__FLAGS_OPTSTR_*) 38 # Output: 39 # string: generated option string for getopt 40 # Returns: 41 # boolean: success of operation (always returns True) 42 43Variable and Function Names 44--------------------------- 45 46All shFlags specific constants, variables, and functions will be prefixed 47appropriately with 'flags'. This is to distinguish usage in the shFlags code 48from users own scripts so that the shell name space remains predictable to 49users. The exceptions here are the standard ``assertEquals``, etc. functions. 50 51All non built-in constants and variables will be surrouned with squiggle 52brackets, e.g. '${flags_someVariable}' to improve code readability. 53 54Due to some shells not supporting local variables in functions, care in the 55naming and use of variables, both public and private, is very important. 56Accidental overriding of the variables can occur easily if care is not taken as 57all variables are technically global variables in some shells. 58 59================================ ======================== 60**type** **sample** 61global public constant ``FLAGS_TRUE`` 62global private constant ``__FLAGS_SHELL_FLAGS`` 63global public variable ``flags_variable`` 64global private variable ``__flags_variable`` 65global macro ``_FLAGS_SOME_MACRO_`` 66public function ``flags_function`` 67public function, local variable ``flags_variable_`` 68private function ``_flags_function`` 69private function, local variable ``_flags_variable_`` 70================================ ======================== 71 72Where it makes sense to improve readability, variables can have the first 73letter of the second and later words capitalized. For example, the local 74variable name for the help string length is ``flags_helpStrLen_``. 75 76There are three special-case global public variables used. They are used due to 77overcome the limitations of shell scoping or to prevent forking. The three variables are: 78 79 - flags_error 80 - flags_output 81 - flags_return 82 83Local Variable Cleanup 84---------------------- 85 86As many shells do not support local variables, no support for cleanup of 87variables is present either. As such, all variables local to a function must be 88cleared up with the ``unset`` command at the end of each function. 89 90Indentation 91----------- 92 93Code block indentation is two (2) spaces, and tabs may not be used. :: 94 95 if [ -z 'some string' ]; then 96 someFunction 97 fi 98 99Lines of code should be no longer than 80 characters unless absolutely 100necessary. When lines are wrapped using the backslash character '\', subsequent 101lines should be indented with four (4) spaces so as to differentiate from the 102standard spacing of two characters, and tabs may not be used. :: 103 104 for x in some set of very long set of arguments that make for a very long \ 105 that extends much too long for one line 106 do 107 echo ${x} 108 done 109 110When a conditional expression is written using the builtin [ command, and that 111line must be wrapped, place the control || or && operators on the same line as 112the expression where possible, with the list to be executed on its own line. :: 113 114 [ -n 'some really long expression' -a -n 'some other long expr' ] && \ 115 echo 'that was actually true!' 116 117.. vim:spell 118.. $Id$ 119