Updated coding style file

CODING_STYLE.TXT

@@ -1,4 +1,4 @@
-Coding style used for my bash projects (v2.1 Oct 2015)
+Coding style used for my bash projects (v2.2 Aug 2016)
 
 ++++++ Header
 
@@ -8,7 +8,7 @@ Always use the following header
 #!/usr/bin/env bash
 
 PROGRAM="program-name" # Long description
-AUTHOR="(C) 20XX-20YY by Orsiris \"Ozy\" de Jong"
+AUTHOR="(C) 20XX-20YY by Orsiris de Jong"
 CONTACT="http://www.example.com me@example.com"
 PROGRAM_BUILD=YYYYMMDDVV
 
@@ -23,8 +23,8 @@ YYYYMMDDVV (Year, Month, Day, Revision): Example: 2015012402 = 2nd revision of 2
 Change old scripts with
 for i in $(grep -r '#!/bin/bash' * |cut -f1 -d':'); do sed -i 's&#!/bin/bash&#!/usr/bin/env bash&g' $i; done
 
-
 type instead of type -p for bash test (other shells don't know -p)
+
 ++++++ Indentation
 
 Using tabs
@@ -38,59 +38,78 @@ Some command # comment
 
 ++++++ Work comments
 
-Whenever there is some idea to postpone, use #TODO[-version]:[dev-name:] some remark
+Whenever there is some idea to postpone, use #TODO(priority):[dev-name:] some remark
-A marker must be left where on the line a dev is working (when the work isn't finished). Marker is #WIP:dev-name: some remark
+Priority can be critical, high, medium, low, verylow. No release can happen if there are TODOs other than low or verylow.
+Example: #TODO(high):deajan: need to do something
+
+A "work in progress" marker must be left on the line a dev is working when it's work isn't finished). Marker is #WIP:dev-name: some remark
 dev-name is mandatory if more than one person is coding
-Example: #TODO-v2.1:deajan: need to do something
+Example: #WIP:deajan: missing function something
 
 ++++++ Variables
 
-All local variables are lowercase, separated by _ (ex: low_wait)
+All local variables names have each first letter of the words uppercase and all others lowercase, except for the first word where all letters are lowercase
-All global variables full upercase, separated by _ (ex: EXEC_TIME)
+Example: someLongVariable
-All environment variables (verbose, silent, debug, etc) have prefix _ and are full upercase, separated by _ (ex: _PARANOIA_DEBUG)
+All global variables are full upercase, separated by _
+Example: EXEC_TIME
+All environment variables (verbose, silent, debug, etc) have prefix _ and are full upercase, separated by _
+Example: _PARANOIA_DEBUG
 
 ++++++ Functions
 
-Every word in a function begins with an uppercase (ex: SomeFunctionDoesThings)
+All function names should begin with an uppercase letter for every word, the other letters should be lowercase
+Example: SomeFunctionThatRocks
 
-Define functions this way. Use sed ':a;N;$!ba;s/\n{\n/ {\n/g' to adapt when opening bracket is on a new line.
+Bash does not provide any checks against missing function arguments. Also, missing quotes can lead to an inconsistent number of arguments.
-
+Most functions should have a first line that calls the special function __CheckArguments, which checks the number of given arguments for a function in order
-function something {
+to find possible problems. Number of arguments are given as first argument to __CheckArguments.
+__CheckArguments will only trigger when the script is launched with _PARANOIA_DEBUG=yes. Also, it will only exist in the debug version.
+Use the following convention for function definition:
 
+function SomeFunction {
+	__CheckArguments 0 $# ${FUNCNAME[0]} "$@"               #__WITH_PARANOIA_DEBUG
+	...	
 }
 
-If function has some arguments, use local variable names that are more readable than $1...$n. Explain via comments what those variables contain if needed.
+Use sed ':a;N;$!ba;s/\n{\n/ {\n/g' to convert functions that have opening brackets on a new line.
 
-function anotherthing {
+If the function has arguments, use local variable names that are more readable than $1...$n. Explain via comments what those variables contain if needed.
-	local var_name="${1}"
+Declare arguments before launching __CheckArguments:
-	local other_var_name="${2}" # This variable contains stuff
+
+function AnotherFunction {
+	local varName="${1}"
+	local otherVarName="${2}" # This variable contains stuff
+	__CheckArguments 2 $# ${FUNCNAME[0]} "$@"		#__WITH_PARANOIA_DEBUG
+	...
 }
 
 Functions should always have return status
-function thirdthing {
+function RandomFunction {
-	some_command
+	...
 	return $?
 }
 
 ++++++ Sub functions
 
-When a function is a subroutine of another function, it is called _SomethingAsSubFunction
+When a function is a subroutine of another function, it is called _SomethingAsSubFunction:
+Example:
 
-++++++ Function argument check
+function _ApplyLocally
+function _ApplyRemotely
+function Apply
 
-Bash does not provide any checks against missing function arguments. Also, missing quotes can lead to an inconsistent number of arguments.
+++++++ For and While statements
-Every function call will be checked by __CheckArguments which takes the number of arguments, $# (the real number of args given), the parent function name and the parent function's arguments.
-__CheckArguments will trigger a critical error if number of arguments if incorrect. This will also prevent silent typo errors.
-Ex:
 
-function Something {
+For and while statements will have the "do" part on the first line.
-	local some="${1}"
+Example:
-	local other="${2}"
-	local args="${3}"
-	__CheckArguments 3 $# $FUNCNAME "$*"
 
-__CheckArguments will only trigger if script is called with DEBUG=yes
+for i in "${var[@]}"; do
-Also, with PARANOIA_DEBUG=yes, __CheckArguments will recount all arguments given by "$*" and compare. This can mislead if arguments contain spaces.
+	...
+done
+
+while [ $i -eq 1 ]; do
+	...
+done
 
 ++++++ If statements
 
@@ -106,7 +125,7 @@ fi
 
 A logging function is available with the following levels of logging:
 
-- DEBUG: Only log this when DEBUG flas is set in program. Any command forged for eval should be logged by this.
+- DEBUG: Only log this when DEBUG flas is set in program. Any command forged for eval instruction should be logged by this.
 - NOTICE: Standard messages
 - WARN: Requires attention
 - ERROR: Program produced an error but continues execution
@@ -128,7 +147,7 @@ cmd=$SSH_CMD' "some; commands \"'$VARIABLE'\" some; other; commands" > some_file
 ++++++ File variables
 
 All eval cmd should exit their content to a file called "$RUNDIR/osync.$FUNCNAME.$SCRIPT_PID"
-Dots are used instead of '_' so variables can be separated with a forbidden char in variables, so they get detected.
+Dots are used instead of '_' so variables can be separated with a forbidden char in variable names, so the separtors apply as wished.
 
 ++++++ Finding code errors
 
@@ -154,3 +173,11 @@ function FunctionName {
 #__ENDFUNC
 
 These functions are inserted into code that has placeholders like #__FUNC:FuncName
+
++++++++ Exit codes
+
+Normal exit code = 0
+Run with errors exit code = 1
+Run with warnings exit code = 2
+Wrong shell exit code = 127
+Usage function exit code = 128