From d79f53760b968a16604f4858e8d34f07b667615b Mon Sep 17 00:00:00 2001 From: deajan Date: Mon, 22 Aug 2016 10:31:47 +0200 Subject: [PATCH] Updated coding style file --- CODING_STYLE.TXT | 95 +++++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/CODING_STYLE.TXT b/CODING_STYLE.TXT index 524c639..da88698 100644 --- a/CODING_STYLE.TXT +++ b/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 -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 +Whenever there is some idea to postpone, use #TODO(priority):[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 global variables full upercase, separated by _ (ex: EXEC_TIME) -All environment variables (verbose, silent, debug, etc) have prefix _ and are full upercase, separated by _ (ex: _PARANOIA_DEBUG) +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 +Example: someLongVariable +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 +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 something { - +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 { - local var_name="${1}" - local other_var_name="${2}" # This variable contains stuff +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. +Declare arguments before launching __CheckArguments: + +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 { - some_command +function RandomFunction { + ... 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. -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: +++++++ For and While statements -function Something { - local some="${1}" - local other="${2}" - local args="${3}" - __CheckArguments 3 $# $FUNCNAME "$*" +For and while statements will have the "do" part on the first line. +Example: -__CheckArguments will only trigger if script is called with DEBUG=yes -Also, with PARANOIA_DEBUG=yes, __CheckArguments will recount all arguments given by "$*" and compare. This can mislead if arguments contain spaces. +for i in "${var[@]}"; do + ... +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