How to Comment in Bash

Introduction

Comments in bash scripting, and programming in general, help make a program easier to understand. When a program runs, the interpreter ignores the commented lines. However, comments help with overall program readability.

When looking at the code later, it helps to have descriptive and valuable explanations about what the code does. Commenting out code for later use is a common practice and is an essential part of programming and bash scripting.

This tutorial demonstrates how to use comments and the best commenting practices in bash scripts.

Prerequisites

• A system running Linux.
• Access to the command line/terminal.
• A text editor, such as Vi/Vim.

How to Comment in Bash

When writing bash scripts, any text after a hash sign (#) indicates the start of a comment, and any text after # in the same line does not execute.

When using a text editor or IDE, comments are colored differently from the rest of the code. They are easy to notice and search for in more extended codes.

shopt -s interactive_comments

The one exception is the shebang (#!), which is typically on the first line of the script. The shebang tells the operating system which interpreter to use for the code.

Inline comments after the shebang result in a "No such file or directory" error.

Single Line and Inline Bash Comment

Both single line and inline comments in bash scripts start with the hash sign (#):

# This is a comment

The additional space after the sign is not necessary. However, it helps with readability.

Follow the example below to create a script with comments:

1. Open the terminal (CTRL+ALT+T) and create a script using Vi:

vi comment.sh

2. Add the following code:

# A comment is considered a single line if you do not press Enter. Below is the shebang, indicating the script uses the bash shell.
#!/bin/bash
# This is a single line comment above a command.
echo "Hello world!" # This is an inline comment.
# This is a single line comment below a command.

The script includes the following lines:

• Line 1 is a single line Bash comment. Visually, the statement spans over two lines.
• Line 2 is the shebang. The script executes using the Bash shell interpreter, located in /bin/bash.
• Lines 3 and 5 are also single line comments before and after a command, respectively.
• Line 4 is a simple echo command with an inline comment.

3. Save and close Vi:

:wq

4. Change the script's permissions to executable:

chmod +x comment.sh

5. Lastly, run the script with:

./comment.sh

The comments do not display when executing the script.

Multiline and Block Bash Comment

To create multiline bash comments, start each line with the hash sign (#):

# This is the first line
# This is the second line

Another unconventional way to create multiline block comments is to use the bash null command (:) together with the heredoc notation:

: << 'COMMENT'
This is the first line
This is the second line
COMMENT

Fundamentally, bash does not support block comments. This method works as a hack if a block comment is essential for a specific case.

Try the example below to see how multiline and block comments work in bash scripts:

1. Open the terminal (CTRL+ALT+T) and create a shell script using Vi:

vi multiline.sh

2. Copy and paste the following code:

: << 'COMMENT'
This is a multiline block comment
using the single quote heredoc
and bash null command.
COMMENT
echo "Hello world!"
# This is a multiline comment
# using the single line notation.

The code does the following:

• Line 1 and 5 are the heredoc delimiters.
• Lines 2-4 are the block comment contents.
• Line 6 is the echo command.
• Lines 7-8 are multiple single line comments, which act as multiline comments.

3. Save the file and close Vi:

:wq

4. Change the script permissions to executable:

chmod +x multiline.sh

5. Finally, run the script to see the output:

./multiline.sh

The terminal output shows only the result in the echo command, while commented lines do not show.

Best Practices and Tips for Bash Comments

Although there are no specific rules for commenting in bash, certain practices are helpful when using comments. These practices and tips intend to help you make the most out of commenting in bash.

1. Include a File Header

All scripts that aren't as apparent at first glance should include a file header. The header serves several purposes:

• Explains what the code does at a glance.
• Indicates the authorship.
• Explains the license notice and provides the permission statement for copyrighted code.

Use comments at the beginning of a code to explain these points. Additionally, if a code is part of a project, include the project name.

2. Avoid Unconventional Block Comments

Although block comments are possible in bash scripts, it is a bad habit to use them. The code is not as easily noticeable as a regular comment because text editors do not render them as comments. Additionally, searching is much easier when there is a unified commenting syntax.

3. Avoid Long and Unnecessary Comments

Keep comments as short as possible and to the point. Verbosity is unnecessary, and it makes the code harder to read.

Likewise, only comment on code which is hard to grasp. A comment on a simple echo command is unnecessary, whereas code that uses a complex regex statement requires a quick indication of what it does.

4. Comments and Functions

All bash functions benefit from comments which explain the purpose, expected inputs, and outputs. The exception is short pieces of code that are apparent.

State the following for each function:

• Brief description of the operation.
• A list of global or modified variables.
• The expected input arguments.
• What the process outputs to the terminal.
• The expected return values.

Below is an example for a function which documents each of the previous points:

PREFIX="Hello "
#### FUNCTION BEGIN
# Prints a greeting
# GLOBALS: 
# 	PREFIX
# ARGUMENTS: 
# 	Name as a String to use for greeting
# OUTPUTS: 
# 	Writes String to STDOUT
# RETURN: 
# 	0 if success, non-zero otherwise.
### FUNCTION END
function () {
	echo "${PREFIX}: $1!"
}

Adjust the example to your use case.

5. Label Consistently

Use comments to label code that needs improvement, implementation, or modification. Create a consistent commenting label for a different task to make it easier to search through the comments.

For example, start and end each function explanation with # FUNCTION BEGIN, or add # TODO comments for future tasks. Likewise, decide whatever labels seem suitable and stay consistent throughout the code.

Conclusion

After reading this tutorial, you know how to write a bash comment. Follow the tips and best practices to use bash comments effectively in your scripts.