Comments

Comments should be indented to the same level as the code they are commenting if they appear above a block of code. Inline comments can be added to a single line if they do not push the line beyond 79 characters. Single-line comments should not end with a period. All comments should capitalize the first word unless that would break a reference to a case-sensitive object such as a variable, utility, manual, et cetera.

#
# Comment above a block consisting of 4 or more lines
#
if some condition; then
    line1
    line2
fi

# Comment above a block consisting of 3 lines of less
if some condition; then
    line
fi

some condition && foo=bar # Comment

Multiline comments should end with a period.

#
# Multi-line comment above a block consisting of 4 or more lines. Lines break
# at column-80 (which should never contain any character).
#
if some condition; then
    line1
    line2
fi

# Multi-line comment above a block consisting of 3 lines or less. Lines break
# at column-80 (which should never contain any character).
if some condition; then
    line
fi

some condition && foo=bar # Multi-line comment for a single line. Line breaks
    # at column-80 (which should never contain any character).

When commenting lines of code to disable their execution, use #? instead of the traditionally used #.

#
# Comment above a block of 4+ lines of commented-out code
#
#?if some condition; then
#?    line1
#?    line2
#?fi

# Comment above a block of 1-3 lines of commented-out code
#?if some condition; then
#?    line
#?fi

#?some condition && foo=bar # Comment after commented-out line

If it is not obvious from reading a line that execution is prematurely terminated, add # NOTREACHED as a comment.

case "$flag" in
...
*) usage # NOTREACHED
esac

some condition && myfunc # NOTREACHED

If a result is ignored, add a comment to the effect.

printf "< Press ENTER to continue >"
read ans # Ignored

Last updated