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.

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.

Decorating comments using ASCII symbols

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.

Decorating comments using whitespaces

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.

People Also Ask

Can I call the symbol (#!) a comment in Bash ?
No, you can call the symbol (#!) ‘shebang’. But it’s not a comment in Bash.
Do I need to update comments if my script changes?
Yes, if your script changes, review the codes and update your comments according to the script.

Should I comment every line in my bash script?
Commenting every line in the Bash script is unnecessary. Instead, try to comment only on complex & puzzling portions of the code.

Is there any tool to generate comments in bash scripts automatically ?
There are several tools to generate comments automatically based on the code structure and function.

Related Articles


<< Go Back to Bash Comments | Bash Scripting Tutorial

5/5 - (3 votes)
Nadiba Rahman

Hello, This is Nadiba Rahman, currently working as a Linux Content Developer Executive at SOFTEKO. I have completed my graduation with a bachelor’s degree in Electronics & Telecommunication Engineering from Rajshahi University of Engineering & Technology (RUET).I am quite passionate about crafting. I really adore exploring and learning new things which always helps me to think transparently. And this curiosity led me to pursue knowledge about Linux. My goal is to portray Linux-based practical problems and share them with you. Read Full Bio

Leave a Comment