kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 1 | Coding Standards |
| 2 | ================ |
| 3 | |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 4 | shFlags is more than just a simple 20 line shell script. It is a pretty |
| 5 | significant library of shell code that at first glance is not that easy to |
| 6 | understand. To improve code readability and usability, some guidelines have |
| 7 | been set down to make the code more understandable for anyone who wants to read |
| 8 | or modify it. |
| 9 | |
| 10 | Function Documentation |
| 11 | ---------------------- |
| 12 | |
| 13 | Each 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 | |
| 29 | Here 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 | |
kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 43 | Variable and Function Names |
| 44 | --------------------------- |
| 45 | |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 46 | All shFlags specific constants, variables, and functions will be prefixed |
| 47 | appropriately with 'flags'. This is to distinguish usage in the shFlags code |
kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 48 | from users own scripts so that the shell name space remains predictable to |
| 49 | users. The exceptions here are the standard ``assertEquals``, etc. functions. |
| 50 | |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 51 | All non built-in constants and variables will be surrouned with squiggle |
| 52 | brackets, e.g. '${flags_someVariable}' to improve code readability. |
kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 53 | |
| 54 | Due to some shells not supporting local variables in functions, care in the |
| 55 | naming and use of variables, both public and private, is very important. |
| 56 | Accidental overriding of the variables can occur easily if care is not taken as |
| 57 | all variables are technically global variables in some shells. |
| 58 | |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 59 | ================================ ======================== |
| 60 | **type** **sample** |
| 61 | global public constant ``FLAGS_TRUE`` |
| 62 | global private constant ``__FLAGS_SHELL_FLAGS`` |
kate.ward | 1e1a098 | 2013-01-14 22:15:26 +0000 | [diff] [blame] | 63 | global public variable ``flags_variable`` |
| 64 | global private variable ``__flags_variable`` |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 65 | global macro ``_FLAGS_SOME_MACRO_`` |
kate.ward | 1e1a098 | 2013-01-14 22:15:26 +0000 | [diff] [blame] | 66 | public function ``flags_function`` |
| 67 | public function, local variable ``flags_variable_`` |
| 68 | private function ``_flags_function`` |
| 69 | private function, local variable ``_flags_variable_`` |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 70 | ================================ ======================== |
kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 71 | |
kate.ward | 1e1a098 | 2013-01-14 22:15:26 +0000 | [diff] [blame] | 72 | Where it makes sense to improve readability, variables can have the first |
| 73 | letter of the second and later words capitalized. For example, the local |
| 74 | variable name for the help string length is ``flags_helpStrLen_``. |
| 75 | |
| 76 | There are three special-case global public variables used. They are used due to |
| 77 | overcome the limitations of shell scoping or to prevent forking. The three variables are: |
| 78 | |
| 79 | - flags_error |
| 80 | - flags_output |
| 81 | - flags_return |
kate.ward | bcd6839 | 2008-11-12 20:15:30 +0000 | [diff] [blame] | 82 | |
| 83 | Local Variable Cleanup |
| 84 | ---------------------- |
| 85 | |
| 86 | As many shells do not support local variables, no support for cleanup of |
| 87 | variables is present either. As such, all variables local to a function must be |
| 88 | cleared up with the ``unset`` command at the end of each function. |
| 89 | |
| 90 | Indentation |
| 91 | ----------- |
| 92 | |
| 93 | Code block indentation is two (2) spaces, and tabs may not be used. :: |
| 94 | |
| 95 | if [ -z 'some string' ]; then |
| 96 | someFunction |
| 97 | fi |
| 98 | |
| 99 | Lines of code should be no longer than 80 characters unless absolutely |
| 100 | necessary. When lines are wrapped using the backslash character '\', subsequent |
| 101 | lines should be indented with four (4) spaces so as to differentiate from the |
| 102 | standard 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 | |
kate.ward | 8ccc299 | 2011-06-10 11:15:05 +0000 | [diff] [blame] | 110 | When a conditional expression is written using the builtin [ command, and that |
| 111 | line must be wrapped, place the control || or && operators on the same line as |
| 112 | the 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!' |
kate.ward | 274784e | 2008-11-14 00:09:18 +0000 | [diff] [blame] | 116 | |
| 117 | .. vim:spell |
| 118 | .. $Id$ |