If you've looked at almost any Bash script, you've probably noticed lines that begin with the # character.

These lines aren't commands, variables, or functions. They're comments—text written for humans rather than for Bash itself.

Comments are one of the simplest features of any programming language, but they're also one of the most valuable. Good comments can make a script understandable months or even years after it was written, while a script without comments can quickly become difficult to maintain—even for its original author.

In this article, we'll explore how comments work in Bash, when you should use them, common mistakes beginners make, and a few best practices that will make your scripts much easier to read.

What Is a Comment?

A comment is text that is ignored by the Bash interpreter.

When Bash encounters a line beginning with #, it skips everything from that # character until the end of the line.

This allows you to leave notes inside your scripts without affecting how they execute.

For example:

#!/bin/bash

# This is a comment.
echo "Hello, world!"

Output:

Hello, world!

The comment never appears on the screen because Bash completely ignores it.

Why Are Comments Important?

Imagine opening one of your scripts six months after writing it.

Will you remember why you wrote every line?

Probably not.

Comments exist to explain:

• why something is being done
• what a section of code is responsible for
• assumptions the script makes
• unusual or complex logic
• warnings for future changes

Good comments make code easier to maintain—not only for other people, but for your future self.

Single-Line Comments

The most common type of comment is a single-line comment.

# Backup directory
BACKUP_DIR="/backup"

# Archive old logs
tar -czf logs.tar.gz logs/

Each line starts with a #.

Everything after that character is ignored until the end of the line.

Multiple Comments

Because Bash doesn't support block comments, each line must be commented individually.

Example:

#!/bin/bash

# Script Name: backup.sh
# Author: John Doe
# Version: 1.0
# Description:
# Creates a compressed backup
# of the current project.

Although this requires more typing, it's also very explicit and easy to read.

Bash Does Not Have Block Comments

Unlike languages such as C, Java, or JavaScript, Bash has no syntax like:

/*
Multiple
lines
*/

or

<!-- XML -->

Every line must begin with its own #.

For example:

# First line
# Second line
# Third line

If you forget the # on one line, Bash will attempt to execute it as a command.

Inline Comments

Comments don't have to occupy an entire line.

They can also appear after a command.

Example:

PORT=8080    # Development server

or

mkdir backups    # Create backup directory

This is perfectly valid.

However, avoid making inline comments too long, as they can make the code harder to read.

Organizing Large Scripts

Comments are especially useful for dividing a long script into sections.

For example:

#!/bin/bash

##################################################
# Configuration
##################################################

BACKUP_DIR="/backup"
LOG_DIR="/logs"

##################################################
# Validate Input
##################################################

if [ $# -eq 0 ]; then
    echo "Missing argument."
    exit 1
fi

##################################################
# Main Processing
##################################################

echo "Starting backup..."

Many developers use decorative separators like these to make navigation easier.

Explain Why, Not What

One of the most common mistakes beginners make is writing comments that simply repeat the code.

For example:

# Print hello
echo "Hello"

The comment adds no useful information.

A better comment explains why:

# Display a welcome message for first-time users
echo "Hello"

The code already tells us what it does.

The comment should explain why.

Commenting Out Code

Comments are often used temporarily while testing.

Instead of deleting code, you can disable it.

Example:

#!/bin/bash

echo "Starting..."

# rm -rf /tmp/test

echo "Finished."

The dangerous command won't execute because it's now a comment.

This is extremely useful while debugging.

However, don't leave large sections of dead code commented out forever.

If the code is no longer needed, remove it.

Your version control system (such as Git) already remembers previous versions.

A Practical Example

Let's write a small script.

#!/bin/bash

# Ask the user for their name
read -p "Enter your name: " NAME

# Greet the user
echo "Hello, $NAME!"

# End of program

The comments explain each step without cluttering the script.

Even someone completely new to Bash can understand what's happening.

A Common Beginner Mistake

Many beginners assume that every line beginning with # is a comment.

There is one important exception.

Look at the first line of almost every Bash script:

#!/bin/bash

This starts with #, but it is not treated as a normal comment.

This special line is called the shebang (or hashbang).

It tells the operating system which interpreter should execute the script.

We'll discuss the shebang in detail in the next article because it deserves its own explanation.

Apart from this special case, lines beginning with # are simply comments.

Documentation Headers

Many developers begin every script with a short documentation block.

Example:

#!/bin/bash

##################################################
# Script: backup.sh
# Purpose:
# Creates daily backups of project files.
#
# Author: dolpa
# Version: 1.2
# Last Updated: 2026-08-06
##################################################

This immediately tells readers what the script does before they even begin reading the code.

Best Practices

Here are a few simple guidelines for writing good comments:

• Write comments for humans, not for Bash.
• Explain why, not what.
• Keep comments short and meaningful.
• Update comments when the code changes.
• Remove outdated comments that no longer match the code.
• Use comments to divide large scripts into logical sections.
• Avoid commenting every single line unless you're writing educational examples.

Conclusion

Comments may seem like one of the simplest features of Bash, but they're also one of the most important. They don't change how your script runs, but they dramatically improve how easy it is to understand, debug, and maintain.

Whether you're writing a quick automation script or a project with hundreds of lines of code, taking a few moments to add clear, meaningful comments is time well spent. Your future self—and anyone else who reads your code—will thank you for it.

In the next article, we'll look at the one important exception to the rule that every line beginning with # is a comment: the shebang (#!/bin/bash), which tells the operating system how to execute your script.