Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Bash Syntax

Bash comments and script documentation

Reference for comments in Bash: the # character, where it does and does not start a comment, block comments with here-documents and a pattern for self-documenting scripts.

In Bash, a word that begins with # starts a comment, and everything after it up to the end of the line is ignored. There is no block-comment syntax; people use one # per line, or a few tricks involving the : command and here-documents.

Because # is only special at the start of a word, it can appear freely inside a word (file#1, ${#var}, $#) and inside quotes, which causes most of the confusion around shell comments.

Terminal
# a full-line comment
echo hello   # a trailing comment
: <<'NOTE'
A pseudo block comment.
NOTE

Try it

Bash Where # starts a comment and where it does not

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Block comments and a self-documenting script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
# comment text
command  # trailing comment
: 'text that is parsed but does nothing'
: <<'EOF'
text that is never executed
EOF
Name Description
# Starts a comment when it is the first character of a word. Runs to the end of the line.
: The null command. It does nothing and returns 0, but its arguments are still expanded.
<<'WORD' A here-document with a quoted delimiter: no expansion happens inside, so the text is inert.
#! On line 1 only: the shebang.

Returns: comments produce no status. : returns 0.

Errors and edge cases: a comment cannot be continued with a backslash. In an interactive shell, # comments only work if shopt -s interactive_comments is on (the default in Bash).

Usage notes

  • Quoted-delimiter trick. : <<'EOF' is the safe block comment: because the delimiter is quoted, $(...) and backticks inside are not executed. With an unquoted delimiter, commands in substitutions would actually run.
  • : 'text' is risky. The text is a real argument: it is parsed, so an unbalanced quote or a single quote inside ends the string early. Prefer the here-document form, or just prefix every line with #.
  • Comment the why, not the what. # retry: the API returns 503 during deploys helps; # increment i does not.
  • File header. A good header lists the purpose, usage, required tools and exit codes. A line prefix like #/ lets the script print them with grep '^#/' "$0".
  • Linters. Tools like ShellCheck read special comments: # shellcheck disable=SC2086 silences one warning on the next line.
  • Documenting functions. Put a short comment line above each function stating the arguments and what it prints or returns.
  • Keyboard shortcut. In an interactive shell, Alt+# (readline) turns the current line into a comment, a handy way to park a half-typed command.