This post was originated by Stephen Phil Hill (Stephen.p.Hill@alcatel-lucent.com) on Oct 8, 2008. As an experienced developer in SU (software upgrade), Phil has spent years on writing KSH and TCL scripts. More ever, this KSH coding standard has been a necessary manual/rules in ALU for all developers who write shell scripts. This post is allowed by Stephen Hill himself. Any question, comment or suggestion, please leave a message here or email to me (dave.tian@alcatel-lucent.com) or Phil.
NOTE: These suggestions, recommendations, and rules are not actual requirements of the project. Instead they are a combination of recommendations that help improve code efficiency and robustness, recommendations that help smooth the code inspection process, and even some style suggestions. Do not be concerned that you must follow these exactly – but be prepared for a slower code inspection if you disregard them totally.
NOTE: These standards assume ksh93 is being used. At the moment all recommendations and code used illustrating them are also compatible with ksh88. Compatibility with bash is not guaranteed but many of the rules apply equally well to bash code.
To determine the ksh version you are using from the cmd-line, simply enter Ctrl-v. This works in either EMACS or VI line-editing mode.
You can also execute:
print ${.sh.version}
for the same result.
If your program needs to verify this at run time one other way is to check on specific functionality:
if [[ $'x' == x ]] ; then
echo "is using ksh93 parsing"
fi
some very minimal Style recommendations
RULE : indent via tabs, not spaces or a mixture of tabs and spaces.
RECOMMENDATION: an exception – wrapping long lines. It can look very readable if you indent the wrap the same number of tabs as the first line, plus 4 spaces.
Eg:
command -a -b -c -d --arg1 stuff --arg2 stuff
--arg3 stuff --arg4 stuff
next command
So the first line is indented one tab. The continuation on the second line is by one tab then 4 spaces. The following line returns to one tab indentation.
This preserves a reasonable alignment for people that use different tabstop settings.
RULE : declare functions before ‘main body’ code in your programs. Don’t mix and match.
Exceptions – maybe loading libraries, typesets of variables, etc.
RECOMMENDATION : Label the main body of the program
At the point of the “main body” start put a ksh comment that includes the word “main”. It helps us old-timer C-programmers out. Eg:
# Begin "main()" program body.
RULE : at least some minimal function prologs
RECOMMENDATION : It can be pretty brief. Just a sentence or two on what it does.
RULE : Don’t put too much. You don’t want to give explicit detail there and have to update it every time you change one line of code. Be realistic – it won’t be updated and it will be wrong in no time.
Where to put the then or do
if [[ condition ]] then stuff fi while [[ condition ]] do stuff done
-VS-
if [[ condition ]] ; then stuff fi while [[ condition ]] ; do stuff done
RECOMMENDATION: I have a personal preference for the second/shorter method, but I won’t try to make any rule on that. The separate line version doesn’t seem to add any readability or anything else I can see though…
RULE: Just don’t switch mid-stream. If you are adding 10 lines in an existing function then follow the method used in the rest of that function.
If you are adding a new function then do what you please.
Ordering functions
When creating a library of functions for use by others, order the functions in some logical way – either by functionality of alphabetically.
Coding standards and recommendations
RULE : use the ksh syntax checker
Always test your code with the build-in syntax checker and fix those warnings before you even try the code. Eg:
ksh -n myscript.ksh
RULE : use the ksh syntax checker on bash code too
If writing bash code, try out the ksh syntax checker on it. You will have to discard some false positives but it is still better than the built-in bash syntax checking.
But also try the bash built-in syntax checker.
RULE : Use [ ] sparingly.
Use of single-square-brackets is somewhat deprecated, largely replaced with double-square-brackets for string and double-paren (( )) for math ops.
It should technically still be allowed for simple tests ( eg, if [ -f myfile ] ) but you will find that many reviewers have a religious zeal for eliminating all uses of [ ]. Use at your own risk.
RULE : Use (( )) for arithmetic expressions.
Using (( )) is almost identical to using ‘let’. Use <>=! style comparison operators. Eg:
if (( $i > 3 )) ; then
if (( i > 3 )) ; then
# note those two forms - using "$i" and using "i"
# are identical except using "i" is faster
(( i-- ))
(( i++ ))
cmd
if (( $? != 0 )) ; then
Note: I don’t know of any benefit for using (( )) around simple assignments, eg:
i=7
RULE : Use double square brackets for string operations.
( couldn’t get the characters through the wiki formatter )
Eg:
if [[ ${HOST_SIDE} != "A" ]]; then
if [[ -e ${VALDATA} ]]; then
RULE : Do not use the old Bourne shell command substitution syntax
x=`cmd`
Instead use the newer KSH syntax for command substitution:
x=$(cmd)
This is much more flexible, nestable, etc.
RULE : Use the {} in variable references almost all the time.
Wrong: $x
Right: ${x}
Right: ${1}
Also Right: $1
It is hard to justify this rule with technical reasons – in 99.9% of usage it won’t matter at all. It actually comes down to a “Because we said so!” kind of rule, and in SU code you need to match existing style somewhat.
RULE : typeset locals
Prevent collision between the global and function-local namespaces – typeset all your variables in functions.
RULE : global/local variable naming conventions
Make globals distinguishable from locals by name, make global variable names in ALL CAPS.
Locals should be all lower case, though mixed case can be used if you feel it is appropriate.
RULE : no littering the filesystem
no tmp files in random directories – put them somewhere specific, not $CWD
BAD: cmd > out
BAD: do_stuff_with out
BAD: rm -f out
BETTER: outfile=/var/tmp/out.$$
BETTER: cmd > ${outfile}
BETTER: do_stuff_with ${outfile}
BETTER: rm -f ${outfile}
RULE : clean up tmp files
clean up after yourself, especially in error legs. trap’s are good for this.
trap "rm -f some_tmp_file ; print -u2 'IT FAILED BADLY'" EXIT
code
more code
# done, clean up and exit. Clear trap to avoid error message.
rm -f some_tmp_file
trap "" EXIT
print "ALL DONE"
exit 0
RULE : get return codes from rsh’d commands
'rsh' doesn’t return the remote return code to you. For that reason we have the wrapper function 'remote_sh' for you to use. There is also the ksh script 'remote_shell'.
Rule of thumb: if you are using it multiple times in one script, definitely use remote_sh. If you are only calling it once you can use remote_shell.
RULE : LEARN ABOUT KSH PATTERN MATCHING!!!!!!!!!!!!
*NEVER EVER use*
echo ${ACRNLIST} | grep [b-km-zA-Z].: > /dev/null
if [ $? -eq 0 ]; then
instead use ksh pattern matching.
if [[ "${ACRNLIST}" == [b-k][m-z][A-Z]: ]]; then
RULE : LEARN ABOUT KSH PATTERN SUBSTITUTION!
*Don’t do this, with an external sed process to launch*
ACRNLIST=$(echo "${ACRNLIST}" | sed "s/,/ /g")
instead use ksh pattern substitution
ACRNLIST=${ACRNLIST//,/ }
In this example the double-slash means the same as the ‘g’ did for sed. See the manpage.
RULE : LEARN ABOUT KSH SUBSTRING SUPPORT:
*Don’t do this, with an external cut process to launch*
x=$(echo ${blah} | cut -c3-10)
y=$(echo ${blah} | cut -c10-)
instead use ksh substring support
x=${blah:2:8}
y=${blah:9}
Remember in converting these that it goes from 1-based to 0-based, and from start-to-end to start-and-length. See the manpage.
Anecdote: I spotted a script with one of those ‘echo | cut’ statements in it. It was inside a nested loop and was being hit about 4400 times to parse some data at script startup. It consistently took 55 seconds to run just that loop on ihgp. Changing that ONE LINE appropriately made the nested loop complete in less than 1 second.
RULE : Check user input data types
If the user is typing an answer to a prompt and the script is using it in a way that bad data may cause a ksh syntax error, check that the data is valid.
Eg, verify that it is numeric:
/bin/echo -e "Enter number of apples desired:c"
read A
if [[ "${A}" != +([[:digit:]]) ]];then
error "answer was not a number"
fi
RULE : Don’t over use ‘rm -fr’
Never use 'rm -fr' on a file, only use the 'r' on a directory.
RULE : Exit with a useful value
Scripts should always exit with a meaningful exit value.
RULE : Return with a useful return value
Functions should almost always return with a meaningful return value.
RULE : Case statements should handle default (usually)
Case statements should almost always include a default case ( with * ) to catch unexpected errors.
RULE : Safer string handling
When comparing strings, use quotes to prevent errors due to unusual strings. Eg:
if [[ "${my_var}" == "done" ]]; then
NOTE: quoting changes it from a pattern match to a string comparison. If you have a pattern you must NOT quote it but you must escape special characters – eg, whitespace.
if [[ "${my_var}" == *it is done ]]; then
RULE : checking if a process is alive by PID
When you have the PID of a process and you need to check if it is still running, some people are tempted to construct elaborate pipelines of ps, grep, sed, and cut. Do not! This is done exactly the same way you would in C, with signal 0:
kill -0 ${pid}
if (( $? != 0 )) ; then
# process is finished
wait ${pid}
echo "process exited with $?"
RULE : use getopts for argument parsing
Possibly KSH93-specific syntax here?
For parsing arguments, usually use getopts. There are exceptions but most scripts that have their own parsing code end up being messy to use and messy to extend later. A simple example follows illustrating several good points:
- Supports longname aliases for the short names ( eg, -v is the same as –verbose )
- Supports longname options that do not have short names ( eg, –help )
- No
#featuredependency concentration on the option spec string since it is multi-line
#
# getopts options spec.
#
OPT_SPEC=":"
OPT_SPEC+="[-][99:-help] "
OPT_SPEC+="[-][98:-examples] "
OPT_SPEC+="[-][v:-verbose] "
OPT_SPEC+="[-][s:-set]: "
OPT_SPEC+="[-][h:-hostname]: "
typeset -u SET_ARG
typeset -i VERBOSE
SET_ARG=""
VERBOSE=0
HOST_ARG=""
# parse command-line
while getopts "${OPT_SPEC}" arg ; do
case "${arg}" in
99)
# --help
print "${USAGE}"
scriptexit "${CURR_CMD}" 0
;;
98)
# --examples
print "${USAGE}"
print "${USAGE2}"
scriptexit "${CURR_CMD}" 0
;;
v)
((VERBOSE++))
;;
s)
SET_ARG=${OPTARG}
SET="Y"
;;
h)
HOST_ARG=${OPTARG}
;;
*)
print "ERROR: Invalid Argument"
print "${USAGE}"
scriptexit "${CURR_CMD}" 1
;;
esac
done
shift $(($OPTIND-1))
davejingtian.org 