|
| 1 | + |
| 2 | +Bourne Shell Coding Conventions |
| 3 | +-------------------------------- |
| 4 | + |
| 5 | +Original version by Mike Shapiro and OpenSolaris Shell Project. |
| 6 | +This document describes the shell coding style used for all the ON shell |
| 7 | +script changes integrated into Solaris. |
| 8 | + |
| 9 | +All new shell code should conform to this coding standard, which is intended |
| 10 | +to match our existing C coding standard. |
| 11 | + |
| 12 | +When in doubt, think "what would be the C-Style equivalent?" |
| 13 | + |
| 14 | +Basic Format |
| 15 | +------------ |
| 16 | + |
| 17 | +Similar to cstyle, the basic format is that all lines are indented by TABs, |
| 18 | +and continuation lines (which in the shell end with "\") are indented by |
| 19 | +an equivalent number of TABs and then an additional four spaces, e.g. |
| 20 | + |
| 21 | +cp foo bar |
| 22 | +cp some_realllllllllllllllly_realllllllllllllly_long_path \ |
| 23 | + to_another_really_long_path |
| 24 | + |
| 25 | +If, For, and While |
| 26 | +------------------ |
| 27 | + |
| 28 | +To match cstyle, the sh token equivalent to the C "{" should appear on |
| 29 | +the same line, separated by a ";", as in: |
| 30 | + |
| 31 | +if [ $x = hello ]; then |
| 32 | + echo $x |
| 33 | +fi |
| 34 | + |
| 35 | +for i in 1 2 3; do |
| 36 | + echo $i |
| 37 | +done |
| 38 | + |
| 39 | +while [ $# -gt 0 ]; do |
| 40 | + echo $1 |
| 41 | + shift |
| 42 | +done |
| 43 | + |
| 44 | +Test Built-in |
| 45 | +------------- |
| 46 | + |
| 47 | +DO NOT use the test built-in. Sorry, executive decision. In our Bourne shell, |
| 48 | +the test built-in is the same as the "[" built-in (if you don't believe me, |
| 49 | +try "type test" or refer to usr/src/cmd/sh/msg.c). So please do not write: |
| 50 | + |
| 51 | +if test $# -gt 0; then |
| 52 | + |
| 53 | +instead use: |
| 54 | + |
| 55 | +if [ $# -gt 0 ]; then |
| 56 | + |
| 57 | +Single-line if-statements |
| 58 | +------------------------- |
| 59 | + |
| 60 | +It is permissible to use && and || to construct shorthand for an "if" |
| 61 | +statement in the case where the if statement has a single consequent line: |
| 62 | + |
| 63 | +[ $# -eq 0 ] && exit 0 |
| 64 | + |
| 65 | +instead of the longer: |
| 66 | + |
| 67 | +if [ $# -eq 0 ]; then |
| 68 | + exit 0 |
| 69 | +fi |
| 70 | + |
| 71 | +DO NOT combine && with { }, as in: |
| 72 | + |
| 73 | +[ $# -eq 0 ] && { |
| 74 | + do something |
| 75 | + do something else |
| 76 | +} |
| 77 | + |
| 78 | +Use a complete "if-then-fi" construct for this instead. |
| 79 | + |
| 80 | +Infinite Loops |
| 81 | +-------------- |
| 82 | + |
| 83 | +The proper way to write an infinite loop in the Bourne shell is to use |
| 84 | +the ":" built-in, which evaluates to true (exit status 0). |
| 85 | +This is better than using "true", because that is *not* a built-in in the |
| 86 | +Bourne shell and thus runs /bin/true. |
| 87 | + |
| 88 | +while :; do |
| 89 | + echo infinite loop |
| 90 | +done |
| 91 | + |
| 92 | +Exit Status and If/While Statements |
| 93 | +----------------------------------- |
| 94 | + |
| 95 | +Recall that "if" and "while" operate on the exit status of the statement |
| 96 | +to be executed. In the shell, zero (0) means true and non-zero means false. |
| 97 | +The exit status of the last command which was executed is available in |
| 98 | +the $? variable. When using "if" and "while", it is typically not necessary |
| 99 | +to use $? explicitly, as in: |
| 100 | + |
| 101 | +grep foo /etc/passwd >/dev/null 2>&1 |
| 102 | +if [ $? -eq 0 ]; then |
| 103 | + echo found |
| 104 | +fi |
| 105 | + |
| 106 | +Instead, you can more concisely write: |
| 107 | + |
| 108 | +if grep foo /etc/passwd >/dev/null 2>&1; then |
| 109 | + echo found |
| 110 | +fi |
| 111 | + |
| 112 | +Or, when appropriate: |
| 113 | +grep foo /etc/passwd >/dev/null 2>&1 && echo found |
| 114 | + |
| 115 | +DO NOT attempt to make pseudo-booleans by setting variables to "true" |
| 116 | +and "false" and then running the variable as a command instead of using a |
| 117 | +comparison test. This is non-idiomatic and confusing to many long-time |
| 118 | +shell programmers. |
| 119 | + |
| 120 | +Use: |
| 121 | + |
| 122 | +good=true |
| 123 | +if [[ $good = "true" ]] ; then |
| 124 | + |
| 125 | +Not: |
| 126 | + |
| 127 | +good=false |
| 128 | +if $good ; then |
| 129 | + |
| 130 | +Variable References |
| 131 | +------------------- |
| 132 | + |
| 133 | +Variable references begin with $ and *may* have their name enclosed in {}'s. |
| 134 | +We prefer to only see the {}'s when required. |
| 135 | +Do not spuriously enclose all your variable names in braces, like this: |
| 136 | +foo=${bar} |
| 137 | + |
| 138 | +This is kind of like writing all your C variable assignments like this: |
| 139 | +foo = (bar); |
| 140 | + |
| 141 | +It compiles, but it looks stupid. |
| 142 | + |
| 143 | +Braces are required around variable names in two specific cases: |
| 144 | + |
| 145 | +(1) when you are forming the string concatenation of your variable with |
| 146 | +another string: |
| 147 | + |
| 148 | +[ $install = yes ] && root="/a/" || root="/" |
| 149 | +hosts=${root}etc/inet/hosts |
| 150 | + |
| 151 | +and (2) when you are using one of the various substitution/assignment operators: |
| 152 | + |
| 153 | +echo ${BASEDIR:-/a} |
| 154 | + |
| 155 | +Variable Naming |
| 156 | +--------------- |
| 157 | + |
| 158 | +We prefer that you adopt a shell variable naming scheme where capitalization |
| 159 | +provides additional meaning (as in our C style): use CAPITAL letters for |
| 160 | +variables that are exported into the environment, or are equivalent to C |
| 161 | +constants or #defines. Use lowercase letters for other variable names: |
| 162 | +BASEDIR=/a; export BASEDIR |
| 163 | +argc=$# |
| 164 | + |
| 165 | +This helps your reader immediately understand the implication of modifying a |
| 166 | +given variable (i.e. whether it will be inherited by child processes). |
| 167 | + |
| 168 | +Quoting |
| 169 | +------- |
| 170 | + |
| 171 | +Quick review of the quoting basics: |
| 172 | + |
| 173 | +Single quotes ('') mean quote but do not expand variable or backquote |
| 174 | +substitutions. |
| 175 | +Double quotes ("") mean quote but allow expansion. |
| 176 | +Backquotes (``) mean execute the command and substitute its standard output |
| 177 | +(note: stderr is unchanged and may "leak" through unless properly redirected) |
| 178 | + |
| 179 | +Use whatever quotes are appropriate for your situation, but please do not |
| 180 | +unnecessarily quote everything (also see 7 above). |
| 181 | + |
| 182 | +For example, references to variables controlled by your script do not have to |
| 183 | +be quoted unless you are expecting your variable to expand to multiple tokens, |
| 184 | +or to the empty string. |
| 185 | + |
| 186 | +However, any variable which contains values from outside the script, such as |
| 187 | +user input or filenames, should be quoted to avoid errors from special |
| 188 | +characters, including whitespace |
| 189 | + |
| 190 | +Testing for (Non-)Empty Strings |
| 191 | +------------------------------- |
| 192 | + |
| 193 | +DO NOT test for (non-)/empty strings by comparing to "" or ''. ALWAYS use the |
| 194 | +test operators -n (non-zero-length string) and -z (zero-length string): |
| 195 | + |
| 196 | +if [ -z "$foo" ]; then |
| 197 | + echo 'you forgot to set $foo' |
| 198 | +fi |
| 199 | + |
| 200 | +if [ -n "$BASEDIR" ]; then |
| 201 | + echo "\$BASEDIR is set to $BASEDIR" |
| 202 | +fi |
| 203 | + |
| 204 | +Commenting |
| 205 | +---------- |
| 206 | + |
| 207 | +Shell comments are preceded by the '#' character. Place single-line comments |
| 208 | +in the right-hand margin. Use an extra '#' above and below the comment in the |
| 209 | +case of multi-line comments: |
| 210 | +cp foo bar # Copy foo to bar |
| 211 | + |
| 212 | +# |
| 213 | +# Modify the permissions on bar. We need to set them to root/sys |
| 214 | +# in order to match the package prototype. |
| 215 | +# |
| 216 | +chown root bar |
| 217 | +chgrp sys bar |
| 218 | + |
| 219 | +Pathnames |
| 220 | +--------- |
| 221 | + |
| 222 | +It is always a good idea to be careful about $PATH settings and pathnames when |
| 223 | +writing shell scripts. This allows them to function correctly even when the |
| 224 | +user invoking your script has some strange $PATH set in their environment. |
| 225 | + |
| 226 | +There are two acceptable ways to do this: |
| 227 | + |
| 228 | +(1) make *all* command references in your script use explicit pathnames: |
| 229 | +/usr/bin/chown root bar |
| 230 | +/usr/bin/chgrp sys bar |
| 231 | + |
| 232 | +or (2) explicitly reset $PATH in your script: |
| 233 | +PATH=/usr/bin; export PATH |
| 234 | + |
| 235 | +chown root bar |
| 236 | +chgrp sys bar |
| 237 | + |
| 238 | +DO NOT use a mixture of (1) and (2) in the same script. |
| 239 | +Pick one method and use it consistently. |
| 240 | + |
| 241 | +Command arguments |
| 242 | +----------------- |
| 243 | + |
| 244 | +When passing user input to commands, if the first operand of a command is a |
| 245 | +variable, use -- for any command that accepts this to flag the end of |
| 246 | +arguments to avoid problems if the variable expands to a value startingwith -. |
| 247 | + |
| 248 | +Interpreter Magic |
| 249 | +----------------- |
| 250 | + |
| 251 | +The proper interpreter magic for a shell script should be simply #!/bin/sh. |
| 252 | + |
| 253 | +End of file |
| 254 | +----------- |
| 255 | + |
| 256 | +Following 2 lines should be placed at the end of file: |
| 257 | + |
| 258 | +# __EOF__ |
| 259 | +<empty line> |
0 commit comments