How to Comment in Bash {+Best Practices} – phoenixNAP

Comments

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

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

This tutorial shows you how to use feedback and best practices for commenting in bash scripts.

Prerequisites

A

• system running Linux

. Command line/

• terminal access

. A text

• editor, such as Vi/Vim

.

How to comment on Bash When writing bash

scripts, any text after a

hash sign (#) indicates the start of a comment, and any text after # on the same line is not executed

.

When you use a text editor or IDE, comments have a different color than the rest of the code. They are easy to notice and search in more widespread codes.

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

Online comments after the shebang result in a “There is no such file or directory” error.

Both

single-line and inline Bash comments in bash scripts begin with the hash sign (#): #

This is a comment

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

Use the following example 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, which indicates that the script uses the bash shell. #!/bin/bash # This is a single-line comment above a command. echo “Hello world!” # This is an online 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 instruction spans more than two lines.
• Line 2 is the shebang. The script is executed 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 permissions from the script to executable:

chmod +x comment.sh

5. Finally,

run the script with: ./comment.sh

Comments are not displayed when you run 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 along 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 like a hack if a blocking comment is essential for a specific case.

Try the following example 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 heredoc command and bash null in quotation marks. COMMENT echo “Hello world!” # This is a multiline comment # using single-line notation.

The code does the following:

Lines

• 1 and 5 are the heredoc delimiters

. Lines

• 2-4 are the content of the bulk comment

.

• Line 6 is the echo command

.

• Lines 7-8 are several single-line comments, which act as multi-line comments

.

3. Save the file and close Vi::

wq

4. Change the permissions from the script to executable:

chmod +x multiline.sh

5. Finally, run the script to see

the result: ./multiline.sh

The output of the terminal shows only the result in the echo command, while the commented lines are not displayed

.

Best practices and tips for Bash feedback

Although there are no specific rules for commenting on bash, certain practices are useful when using comments. These practices and tips are intended to help you get the most out of bash feedback.

1. Include

a file header

All scripts that are not so obvious at first glance should include a file header. The header serves several purposes:

• Explain what the code does at a glance

.

• Indicates authorship

.

• Explains the license notice and provides the permission statement for the copyrighted

code.

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

2. Avoid

unconventional

blocking comments

Although blocking comments are possible in bash scripts, it is a bad habit to use them. The code is not as easy to notice as a normal comment because text editors do not render them as comments. In addition, searching is much easier when there is a unified comment syntax.

3. Avoid long and unnecessary comments

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

Similarly, only comment on code that is difficult to understand. A comment on a simple echo command is unnecessary, while 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 explaining purpose, expected inputs, and outputs. The exception is short snippets of code that are obvious.

Indicate the following for each function:

• Brief description

of the operation.

• A list of global or modified variables

. The expected

• input arguments

.

• What the process sends to the terminal

. The

• expected return values. The

following is an example of a function that documents each of the previous points:

PREFIX=”Hello” #### FUNCTION BEGIN # Prints a greeting # GLOBALS: # PREFIX # ARGUMENTS: # Name as a string to use to greet # OUTPUTS: # Type String to STDOUT # RETURN: # 0 If successful, it is not zero otherwise. ### FUNCTION END function () { echo “${PREFIX}: $1!” }

Adjust the example to your use case.

5. Label consistently

Use comments to tag code that needs improvement, implementation, or modification. Create a consistent comment tag for a different task to make comments easier to find.

For example, start and end each function explanation with #FUNCTION BEGIN, or add #ALL comments for future tasks. Similarly, decide which tags seem appropriate to you and stay consistent throughout your code.

Conclusion

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