How to Comment Code in Bash Script
Last updated
Last updated
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.
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.
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 statementecho "Enter name" #Taking user inputread name #Displaying the outputecho "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 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/basha=alpha # inline comment where we assign the variable a valueb=beta # assigning variable $bg=gamma # assigning variable $g echo $a $b $gecho $a `# $b` $g #inline comment where we only comment the variable $becho $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.
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.COMMENTa=alphaecho $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=alphaecho $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/bashcomment1=' We have a multiline comment. Here we have the value of $a.'a=alphaecho $acomment2=' We have a multiline comment. Here we have the value of $b.'b=betaecho $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.
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 inputnumericCheck(){ 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.
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.
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.
