Use Comments in Bash Scripts

Bash script is a language that has multiple functionalities and capabilities, and as a programmer, keeping track of and remembering all the language syntax, especially if it's not your day-to-day language, is hard. For this purpose, we use comments, which allow us to simplify and demonstrate what a part of the code does.

Writing comments is not necessary or obligatory, but it's a good practice, and here's why we use comments in code ?

• Remember the code ? Sometimes you write code and forget it for some time. When you come back, you might not remember why you wrote a particular part of the code. Using comments will help you recall your goal.
• Readability ? Writing comments can help another person read and understand your code.
• Documentation ? Comments help describe what a script does and make its usage simpler.
• Provide context ? Comments help understand the context of a part of the code by describing what it does.

Bash scripts have two ways to include and use comments inside the code. In this article, we will demonstrate them with examples.

Single line comment

Bash, like other scripting languages, has its own way of writing comments. One of the simplest ways to add comments in a Bash script is by using single-line comments to describe a block of code or script.

When we start writing a script, it's often the case that we start with the first line as a shebang (#!) to specify the interpreter. After that line, it's a good practice to write a comment to demonstrate what the entire code does and what the goal is.

Let's make an example here ?

#!/bin/bash  

# This script will print a message to the screen  

In this example, we start the script by specifying bash as the interpreter in the first line ?

#!/bin/bash  

In the second line, we write a single-line comment. To write a single-line comment in Bash, we use the symbol #, followed by the comment we want. In this case, we write This script will print a message to the screen.

# This script will print a message to the screen  

The first line in Bash, often called the shebang (#!/bin/bash), is not a comment. Don't be confused; this line is used to specify the interpreter, even though it starts with the same symbol (#).

Comments in all languages are ignored by the interpreter. In Bash, if you write a script with comments, the interpreter will execute the commands but not the comments. To understand this, let's make an example ?

#!/bin/bash  

# Print Hello to the screen  

echo "Hello"  

This script prints the message Hello to the screen. We add a comment describing this in the second line. When we execute the script, it will run only the part that is not commented out ?

Here, we save the example script in a file called test.sh and run it using the bash command. As a result, we get the message Hello, and the comments are ignored.

Comment Code

Sometimes, when we write a long script and get stuck on errors or don't get the result needed, we use comments to ignore some part of the code we think the problem is in. This operation is called debugging. In simple terms, we search for the error by commenting out code.

Here's an example ?

 #!/bin/bash  

# Print Hello to the screen  

echo "Hello"  

# echo "Welcome" 

In this example, we comment out the code that will show the message Welcome to the screen. But because it's commented out, it will be ignored during execution by the interpreter, and as a result, we will get only the message Hello if we run the script again.

The key takeaway from this is that single-line comments can also be used to ignore parts of the code in the execution phase.

Multiline Comment

Another way to add comments to a script in Bash is by using multiline comments. As the name suggests, it is a comment that spans more than one line.

In the first example, we explained how to use the symbol # to write a single-line comment. For multiline comments, the syntax is different. We don't use #; instead, we use a delimiter, like this ?

#!/bin/bash  

<<COMMENT  

This script will print hello.  
This script uses echo to print the message.  

COMMENT  
echo "Hello"  

The syntax for multiline comments may initially be a bit confusing. Here's how it works ?

• <<COMMENT starts the comment.
• COMMENT ends the comment.
• Everything between these two lines is treated as a comment and is ignored when the script runs.

This can span one line or multiple lines as needed. As a result, when we execute the script, the comments are ignored.

In a Bash script, you can combine single-line comments and multiline comments as needed without affecting the actual code.

Take a look at the following example ?

#!/bin/bash  

<<COMMENT  

This script will print hello.  
This script uses echo to print the message.  

COMMENT  
echo "Hello"  

# This will print the message TutorialsPoint  

echo "TutorialsPoint"  

This example combines single-line and multiline comments.

Another Way to Write Multiline Comments

Another way to write multiline comments in Bash is by using a colon (:) followed by a single quote. The syntax is as follows ?

#!/bin/bash  

: '

This script will print TutorialsPoint.  
This script uses echo to print the message.  

'  
echo "TutorialsPoint"  

Here's how it works ?

• Use a colon (:) followed by a space and a single quote (').
• Close the comment at the end with a single quote (').
• Write your comment text in between.

When you run this script, the comment block is ignored, and you should get the output ?

Customized Comment

Bash allows customization of comments using the colon (:) with a here-document (<<). The syntax looks like this ?

#!/bin/bash  

: <<'comment'  

This script will print TutorialsPoint.  
This script uses echo to print the message.  

comment  

echo "TutorialsPoint"  

This uses a delimiter, which can be any name of your choice, as long as the starting and ending delimiters match. For example, in this script, the delimiter is comment, but you can replace it with anything.

Important Note ? The delimiter is case-sensitive. If the start and end delimiters don't match exactly, you will get an error.

Incorrect example

: <<'comment'  

This script will print TutorialsPoint.  
This script uses echo to print the message.  

'Comment  

Conclusion

Comments are a best practice when writing code because they make the code more readable and easier to understand. They also provide context to the reader.

In this tutorial, we explained different ways to add comments to a shell script. The decision on which method to use depends on your needs and use cases.