We will come across comments in every programming language. They are useful and necessary as they make code clean and readable. Just like we use comments in other programming languages, we can do the same throughout our scripts to make them easily understandable to any person going through the code.
Types of comments in Bash
Comments are simply human-readable explanations written in the scripts. These comment lines are totally ignored by the compiler and hence, they do not execute when we run the script. The sole purpose of the comments are for human reading only. We can classify Bash comments into three categories.
Single line
Whenever we see shell scripts, we will often encounter single line comments as they are self-explanatory and don’t require extensive detailing. We can have single line comments anywhere in the code but there are some practices we should follow to make the code more readable.
Example:
#!/bin/bash
#My first comment
#printing a statement
echo "Enter name"
#Taking user input
read name
#Displaying the output
echo "Hello $name"
#echo "Good day, $name"
To make single line comments in our script, we just need to use the hash (#) symbol to begin commenting. We can have as many comments as we want. Sometimes, we may also use comments to restrict some particular lines of code from executing. In our case we have made sure that the last line of the script, which prints a statement, doesn’t execute.
Inline
Inline comments are comments that share the line with the statement or the code expression. With inline comments we can have the code line as well as the comment present on the same line.
Example:
#!/bin/bash
a=alpha # inline comment where we assign the variable a value
b=beta # assigning variable $b
g=gamma # assigning variable $g
echo $a $b $g
echo $a `# $b` $g #inline comment where we only comment the variable $b
echo $a `# We will not print $b` $g
In this example, we are making the inline comments. The interpreter will read each line of the code till it encounters the #symbol, after which it will move to the next line and continue with the same.
We can also put a comment in between a particular line of code. To do this, We need to comment as we generally do and surround that entire comment expression with backticks (`). As shown in the last two lines of the example, the text from the hash symbol to the second backtick will be treated as a comment.
Multiline
Though Bash doesn’t support block comments we can still insert multiline comments in our scripts.
Approach 1
We will use the heredoc redirection as a workaround to insert a block of comments.
Example
#!/bin/bash
<< 'COMMENT'
We have a multiline comment.
We can use it anywhere.
COMMENT
a=alpha
echo $a
Heredoc is generally brought to use when we need to pass more than one input line to a command. However, if we do not specify any command in the heredoc, the lines will have no effect on our code and will effectively serve as a way to comment multiple lines. We are free to give the heredoc any name.
Approach 2
Another workaround is to use a colon with single quotes
Example
#!/bin/bash
: '
We have a multiline comment.
We can use it anywhere.
'
a=alpha
echo $a
Here we have a block of text enclosed in a delimiter. This type of commenting comes handy when we want to prepare a documentation of the script or its functionality.
Approach 3
Another possible approach is to create variables containing blocks of text.
Example
#!/bin/bash
comment1='
We have a multiline comment.
Here we have the value of $a.
'
a=alpha
echo $a
comment2='
We have a multiline comment.
Here we have the value of $b.
'
b=beta
echo $b
We can initialize any arbitrarily named variable and assign a block of text to serve the purpose of a comment. This can be useful when we want to assign and identify our comments by a name.
Comment Bash Example
We will take an example of a sample script and put all the different types of comments, we have learned so far, to practice.
#!/bin/bash
<< 'COMMENT'
----------------------------------------------------------------------------------
This script checks if the input is a number or not
It takes one argument with the script.
This argument is supposed to be a single word.
If it is a number it will display that the input is a number.
If it is not a number, it will print that the input is not a number.
Run the script as follows
./isNumeric.sh <character>
Ex
./isNumeric.sh 5
----------------------------------------------------------------------------------
COMMENT
# Function to check if the input is numeric or not
#Takes one input
numericCheck()
{
if ! [[ "$1" =~ ^[0-9]+(\.[0-9]+)?$ ]] # numeric regex check
then
# If true, it is numeric.
echo $1 is non numeric.
else
# If false, it is not numeric.
echo $1 is a number.
fi
} #function ends
# Calling the function with the input taken while running the script.
numericCheck $1 #$1 is the first argument
: '
We are taking user input
We pass it to the function
We get the result
'
We have written a script and included the various types of comments we have learned so far. We are free to add as many comments we want. The interpreter will not process any of these comments. However, when we look at this script, even years from now, we will know what exactly we did as the script is pretty detailed. Next, we will learn some of the best practices to include comments.
What should comments include?
- We should have a multiline comment or a series of single line comments after the Shebang line to explain the purpose of the script.
- It must also describe how to run the script along with the arguments needed if any. We should include an example as well for better understanding.
- Comments should explain less obvious parts of the code, the ones which are hard to understand
- We should keep the comments brief.
- We should also avoid the block comments as comments beginning with # are easily noticeable.
- When using functions, we should have multiple single line comments to describe what the function does and the input(s) it requires.
- When invoking the function, we should again comment with the input(s) being supplied.
Conclusion
- Comments make our scripts more readable and understandable.
- Bash provides only single line comments.
- We can use backticks and herdoc to implement inline and block comments respectively.
- We should follow certain rules while making comments.
Comments