Define locals properly with docstrings

99bottles.sh

     #
     # Get predecessor to a number $1
     #
-    case $1 in
-        *nine)      echo ${1%nine}eight;;
-        *eight)     echo ${1%eight}seven;;
-        *seven)     echo ${1%seven}six;;
-        *six)       echo ${1%six}five;;
-        *five)      echo ${1%five}four;;
-        *four)      echo ${1%four}three;;
-        *three)     echo ${1%three}two;;
-        *two)       echo ${1%two}one;;
+    local numeral=$1    # number in word form
+    case $numeral in
+        *nine)      echo ${numeral%nine}eight;;
+        *eight)     echo ${numeral%eight}seven;;
+        *seven)     echo ${numeral%seven}six;;
+        *six)       echo ${numeral%six}five;;
+        *five)      echo ${numeral%five}four;;
+        *four)      echo ${numeral%four}three;;
+        *three)     echo ${numeral%three}two;;
+        *two)       echo ${numeral%two}one;;
         one)        echo zero;;
-        *-one)      echo ${1%-one};;
-        *one)       echo ${1%one};;
+        *-one)      echo ${numeral%-one};;
+        *one)       echo ${numeral%one};;
         ten)        echo nine;;
         eleven)     echo ten;;
         twelve)     echo eleven;;
-        *teen)      teenpred $1;;
-        *ty)        tenspred $1;;
+        *teen)      teenpred $numeral;;
+        *ty)        tenspred $numeral;;
         zero)       echo "";  #to terminate
     esac
 }
     #
     # Get predecessor of a teen $1
     #
-    case $1 in
+    local numeral=$1    # number in word form
+    case $numeral in
         thirteen)   echo twelve;;
-        *)          echo $(crunchprefix $(pred $(uncrunchprefix ${1%teen})))teen;;
+        *)          echo $(crunchprefix $(pred $(uncrunchprefix ${numeral%teen})))teen;;
     esac
 }
 
     #
     # Get predecessor of a multiple of ten $1
     #
-    case $1 in
+    local numeral=$1    # number in word form
+    case $numeral in
         twenty)     echo nineteen;;
-        *) echo $(crunchprefix --tens $(pred $(uncrunchprefix ${1%ty})))ty-nine;;
+        *) echo $(crunchprefix --tens $(pred $(uncrunchprefix ${numeral%ty})))ty-nine;;
     esac
 }
 
     #
     # option `--tens` - multiples of ten are a bit different
     #
+    local numeral       # number in word form
+    local tensop        # 'true' if --tens option is active
     [ $1 = --tens ] && { tensop=true; shift; }
-    case $1 in
-        two)    [ -n "$tensop" ] && echo twen || echo $1;;
+    numeral=$1
+    case $numeral in
+        two)    [ -n "$tensop" ] && echo twen || echo $numeral;;
         three)  echo thir;;
-        four)   [ -n "$tensop" ] && echo 'for' || echo $1;;
+        four)   [ -n "$tensop" ] && echo 'for' || echo $numeral;;
         five)   echo fif;;
-        eight)  [ -n "$tensop" ] && echo eigh || echo $1;;
-        *)      echo $1;;
+        eight)  [ -n "$tensop" ] && echo eigh || echo $numeral;;
+        *)      echo $numeral;;
     esac
 }
 
     #
     # Reverse crunchprefix $1
     #
-    case $1 in
+    local prefix=$1     # numeral crunch-prefix
+    case $prefix in
         twen)   echo two;;
         thir)   echo three;;
         'for')  echo four;;
         fif)    echo five;;
         eigh)   echo eight;;
-        *)      echo $1;;
+        *)      echo $prefix;;
     esac
 }
 
     #
     # Apply peculiarities of English grammar to text on stdin
     #
-    local oneBottle=false  #can effect the following line
+    local oneBottle=false   # 'true' if this line affects the following line
+    local line              # every line
     while read line; do
         line="${line/one more bottles/one more bottle}"
         case "$line" in
     #
     # Fix capitalization of each line on stdin
     #
+    local line      # every line
     while read line; do
         echo -n ${line:0:1} | tr '[:lower:]' '[:upper:]'
         echo ${line#?}
     #
     # Add punctuation to each line on stdin
     #
+    local line      # every line
     while read line; do
         case "${line}" in
             [Ii]f*)     echo ${line},;;
     #
     # Write one verse with number $1
     #
-    local nb=$1
+    local nb=$1     # numeral
     echo $nb bottles of beer on the wall
     echo $nb bottles of beer
     if [ $nb = zero ]; then
     #
     # Make text on stdin nice
     #
+    local first     # first word of a line
+    local rest      # remainder of a line
+    local syl       # number of syllables in the first word
     while read first rest; do
         case "$rest" in
             *beer*)
                 first=${first/zero/no}
-                local syl=$(syllables ${first% *})
+                syl=$(syllables ${first% *})
                 case $syl in  #improve meter
                     1|2)    echo $first 'more' $rest;;
                     *)      echo $first $rest;;
     #
     # Estimate number of syllables in word $1
     #
+    local word=$1   # word (numeral) to do the estimation on
     local n=1
-    case $1 in
+    case $word in
         eleven)     n=2;; #sounds better if not considered 3
         *teen)      n=2;;
         *ty)        n=2;;
         *-*)        n=3;; #don't care about more than 3
     esac
-    case $1 in
+    case $word in
         *seven*)    let $((n = n+1));;
     esac
     echo $n
 }
 
 main() {
+    local breakLine             # bottle-break (or not) line
+    local standardBreakLine     # ^^ standard variant
+    local wastefulBreakLine     # ^^ wasteful (bottle breaks) variant
+    local nb            # beginning number
     standardBreakLine="Take one down and pass it around"
     wastefulBreakLine="If one of those bottles should happen to fall"
-    breakLine=$([ "$1" = --careless ] \
-     && echo $wastefulBreakLine \
-     || echo $standardBreakLine)
-
+    breakLine=$(
+        [ "$1" = --careless ] \
+         && echo $wastefulBreakLine \
+         || echo $standardBreakLine
+    )
     nb=ninety-nine
-
     while [ -n "$nb" ]; do
         verse $nb
         echo