The Art of Commenting in Bash

Why do commenting when it’s not a part of script execution? -such kind of question may cross your mind, right? Well, commenting within codes is a kind of art. Though comments are not executed, they qualify the details of the codes which were written in a confusing way. Anyway, writing thoughtful comments is not everyone’s cup of tea. So, this article will be an essential resource for you while mastering the art of commenting in Bash.

Table of Contents Expand

Key Takeaways

Exploring the art of commenting in Bash script.
Getting ideas for Bash comment decoration.

Best Practices for Writing Effective Comments in Bash

Follow some best practices for writing comments within your programs to maintain good readability:

Easy & Concise Language: Convey easy and concise language so that the intention of the code is clear.
Avoid Commenting ‘What’: Avoid commenting on what the code does as you can see it from the output.
Comment only on the purpose: Focus only on commenting on the purpose of the code and explain why you have implemented it that way.
Skip Redundant comments: Skip redundant comments to avoid merely duplicate ones.
Comment on the complex parts: If your code contains tricky or complex parts, try to explain the logic or algorithm through comments.
Avoid Jargon & Abbreviation: Try to skip excessive jargon and abbreviation in commenting language to avoid readers’ confusion.
Avoid Long Comments: Be careful of comments’ length. Use short comments or chunks of comments providing sufficient information to cut off the boredom for readers.
Leave Complete Comments: Ensure to leave complete comments always otherwise it will mislead the readers.
Recheck & Proofread Comments: Write comments using proper grammar and punctuation, recheck the spelling, and of course proofread these at last because comments are as important as your code.

How to Decorate Comments in Bash?

When you are done learning how to write comments in Bash, you can embellish your code by using various decorative sections of comments. So, organize your Bash comments in different styles, and enrich your script with the following terms:

A. Decorating With ASCII Characters

You can easily decorate comments by using some ASCII characters like ‘+’, ‘–’, ‘=’, ‘|’. Here’s how to decorate comments using ASCII symbols:

Script (ascii.sh) >

#!/bin/bash

# ================================
#  +----------------------------+
#  |     This is a comment      |
#  +----------------------------+
# ================================

echo "Hello, Bash!"

EXPLANATION

Here, in #!/bin/bash: ‘#!’ is called ‘Shebang’. Then,

# ===========================

# +————————————————–+

# | This is a comment |

# +————————————————–+

# =========================== represents comments surrounded by decorative elements of ASCII characters that make the comments look more appealing.

In the above image, I have used ASCII symbols to decorate the comment. Thus, using these symbols, you can create comments and separate different sections of code too.

B. Decorating With Whitespace

Another option for decorating comments is using whitespace. By adding indentation or line spaces, you can highlight a specific comment block and separate it from other sections. Try the example below to decorate comments by using whitespace:

Script (space.sh) >

#!/bin/bash

#   ===== IMPORTANT =====
#
#   Focus on this comment
#
#   =====================

EXPLANATION

Here,

# ===== IMPORTANT =====

# Focus on this comment

# ===================== indicates comments that are decorated by blank lines.

Like the above snapshot, you can decorate comments by bordering them with whitespace. This will create a partition among sections and point out the particular comments block.

3 Important Aspects of Bash Comments

Too many comments with overflowing alignment are very difficult to maintain. So, it’s very important to strike a proper balance between comments and codes in a Bash script. Here, you’ll find how to make a good balance between codes and comments in Bash:

1. Illustrating Complex Codes

Use comments to illustrate complex algorithms or calculations of codes. For a small complex portion, you can use Single-line comments. And for describing a block of a logical section, you can use Multiple-line comments or Block comments.

2. Employing Whitespace

Don’t comment out a script in a congested way. Use proper whitespaces to make a separation between comments & codes and enhance the visual appearance of the script.

3. Utilizing Proper Variable Name

Avoid using baffling variable names. This will only create confusion in the script. Use concise and easy-to-understand variables to reduce the potential for errors in the script.

3 Mistakes to Avoid During Bash Commenting

Comments in bash are generally undervalued. You know, appropriate commenting in proper places can resolve the debugging issues and hours of frustration. So, there are some common mistakes that you need to avoid for mastering the commenting art in Bash:

A. Missing File Header

The file header actually represents describing the purpose of the script. If the script you are using doesn’t have any file header, it will decrease the readability and understandability of the whole script.

B. Unusual Block Comments

Normally, stick to the comments starting with the hash (#) symbol as it enables you to grep quickly through the script. As there is no built-in syntax for block comments in Bash, you need to use alternative notations to append them. So, except for some edge cases, try to avoid unconventional block comments.

C. Missing Function & Variable Comments

Missing function comments & variable comments make a script less accessible and cannot be much helpful for users. So, whenever writing a Bash script, it’s recommended to use function & variable comments so that you can describe every argument, parameter, or variable used in the function or variable section.

Conclusion

Comments are basically used to add some value to the code written on the Bash script. To summarize, you can make a more viable script with understandable codes by adapting the art of commenting.