> For the complete documentation index, see [llms.txt](https://freebsdfrau.gitbook.io/serious-shell-programming/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://freebsdfrau.gitbook.io/serious-shell-programming/style/comments.md).

# 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
```