From d204c88601f822931b268b71d91015c847941c05 Mon Sep 17 00:00:00 2001 From: Kate Ward Date: Mon, 7 Aug 2017 17:55:56 +0200 Subject: Reformatted to Markdown, so renamed accordingly. --- doc/coding_standards.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++ doc/coding_standards.txt | 147 ----------------------------------------------- 2 files changed, 147 insertions(+), 147 deletions(-) create mode 100644 doc/coding_standards.md delete mode 100644 doc/coding_standards.txt (limited to 'doc') diff --git a/doc/coding_standards.md b/doc/coding_standards.md new file mode 100644 index 0000000..b071876 --- /dev/null +++ b/doc/coding_standards.md @@ -0,0 +1,147 @@ +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 declaration +-------------------- + +Declare functions using the following form: + +```sh +doSomething() { + echo 'done!' +} +``` + +One-line functions are allowed if they can fit within the 80 char line limit. + +```sh +doSomething() { echo 'done!'; } +``` + +Function documentation +---------------------- + +Each function should be preceded by a header that provides the following: + +1. A one-sentence summary of what the function does. + +1. (optional) A longer description of what the function does, and perhaps some + special information that helps convey its usage better. + +1. Args: a one-line summary of each argument of the form: + + `name: type: description` + +1. 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` + +1. 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 surrounded 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` built-in command at the end of each function. + +Indentation +----------- + +Code block indentation is two (2) spaces, and tabs may not be used. + +```sh +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. + +```sh +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 built-in [ 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. + +```sh +[ -n 'some really long expression' -a -n 'some other long expr' ] && \ + echo 'that was actually true!' +``` diff --git a/doc/coding_standards.txt b/doc/coding_standards.txt deleted file mode 100644 index b071876..0000000 --- a/doc/coding_standards.txt +++ /dev/null @@ -1,147 +0,0 @@ -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 declaration --------------------- - -Declare functions using the following form: - -```sh -doSomething() { - echo 'done!' -} -``` - -One-line functions are allowed if they can fit within the 80 char line limit. - -```sh -doSomething() { echo 'done!'; } -``` - -Function documentation ----------------------- - -Each function should be preceded by a header that provides the following: - -1. A one-sentence summary of what the function does. - -1. (optional) A longer description of what the function does, and perhaps some - special information that helps convey its usage better. - -1. Args: a one-line summary of each argument of the form: - - `name: type: description` - -1. 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` - -1. 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 surrounded 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` built-in command at the end of each function. - -Indentation ------------ - -Code block indentation is two (2) spaces, and tabs may not be used. - -```sh -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. - -```sh -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 built-in [ 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. - -```sh -[ -n 'some really long expression' -a -n 'some other long expr' ] && \ - echo 'that was actually true!' -``` -- cgit v1.2.3