Bash Comments

When to use Bash comments

Just like comments are used in other programming languages, you can also use them throughout your shell scripts to make them more readable. For example, if you’ve written a script for others to use, comments help explain the purpose of certain lines. They can also help you, the developer, quickly remember your thought process from when you wrote the script.

Comments should be used to complement clean, organized Bash scripts. They should only be used to explain less obvious parts of the code. For example, most developers reading an echo statement will know how it works, but a user-defined function may be harder to immediately understand, so a shell script comment would be helpful there.

Single-line comments

To create a single-line comment in a Bash script, begin the comment with a hash (#) symbol. Bash ignores everything after the hash, so even if you include code snippets in comments, they won’t be executed.

A comment can be on a line alone:

# This is a comment
$ ls path/to/directory

Run in Warp

A comment can also be on the same line as script code:

$ ls path/to/directory  # This is also a valid  way to write comments
Run in Warp

Multiline/Block comments

Unfortunately, there is no built-in way to write multi-line comments in Bash. But here are some workarounds.

Multiple single-line comments

You can use multiple single-line comments to make up a larger overall comment:

# The following code uses the ls command
# The ls command lists the files in a directory.
$ ls path/to/directory

Run in Warp

Using a colon and single quotes

The simplest workaround is using the colon and single quote characters:

: ' 
This comment can be
many lines long
Within this block
'

Run in Warp

Arbitrarily-named variables

You can also assign an arbitrarily named variable to a multi-line string to serve the same purpose as a comment - it’s still a block of text that’s recognizable to anyone using your shell script. This is useful if you want to give the comment a name.

example_comment=' 
This is technically a variable.
But it serves the same purpose as a comment.
'

Run in Warp

HereDoc redirection

You can utilize the HereDoc redirection mechanism as a workaround to write multi-line comments in Bash. Usually, HereDoc is used when you need to pass more than one input line to a command, but if you don’t specify a command, the lines have no effect and can serve as a way to write “comments” spanning multiple lines.

<< 'COMMENT-EXAMPLE' 
  This is a multi-line comment hack.
  You can give the HereDoc any title you want.
  Here we used COMMENT-EXAMPLE.
COMMENT-EXAMPLE

Run in Warp

Keep in mind that commenting through HereDoc is not officially supported by Bash, so it’s best practice to stick to hash symbol comments, or the above.

Read more about commenting in bash in the official bash man pages.