Comments (#)

#!/bin/bash
# Shebang line: written on the first line of a file to specify the interpreter.
# The kernel reads this line and runs the script with the specified shell.

# Single-line comment. Everything from # to the end of the line is a comment.

count=10 # Inline comment. Use this to add a short note to the right of a line of code.

Type	Syntax	Description
Single-line comment	# text	Everything from # to the end of the line becomes a comment. Can be placed at the start of a line or after code on the same line.
Shebang line	#!/path/to/interpreter	Written only on the first line of a file to specify the interpreter. A type of comment, but treated specially by the kernel.

Shell scripts have no dedicated block comment syntax. To comment out multiple lines, add # to the beginning of each line.

Decision	Situation	Reason
Write a comment	The reason why something was implemented a certain way	Design decisions and trade-offs that cannot be understood from the code alone help your future self and other developers.
Write a comment	Complex algorithms or formulas	Add a brief description of what a piece of logic does when its behavior is not immediately obvious at a glance.
Write a comment	At the top of the script	Summarizing the script's purpose, usage, arguments, required permissions, and dependencies at the top lets readers grasp the overview before reading the body.
Write a comment	Temporarily disabled code during debugging	Leaving a note explaining why code was commented out and when it can be removed reduces the risk of forgetting to clean it up later.
No comment needed	Logic that is obvious from reading the code	Comments like # add 1 to i become noise. Clear variable and function names remove the need for such comments.
No comment needed	Change history or deleted code	Because version control (git) is available, there is no need to keep old code or change dates in comments.

A comment block at the top of a script and basic usage of single-line comments.

comment_basic.sh

#!/bin/bash
#
# backup_logs.sh — a script that backs up log files to a specified directory.
#
# Usage:
#   ./backup_logs.sh  
#
# Example:
#   ./backup_logs.sh /var/log /backup/logs
#
# Required permissions: read access to source dir, write access to dest dir

SOURCE_DIR="$1" # path to the source directory
DEST_DIR="$2" # path to the backup destination directory
TIMESTAMP=$(date +"%Y%m%d_%H%M%S") # timestamp appended to the archive filename

# Check that exactly two arguments were provided.
if [ "$#" -ne 2 ]; then
	echo "Usage: $0  " >&2
	exit 1
fi

# Create the destination directory if it does not exist.
if [ ! -d "$DEST_DIR" ]; then
	mkdir -p "$DEST_DIR"
fi

ARCHIVE_NAME="${DEST_DIR}/logs_${TIMESTAMP}.tar.gz"

# Create a tar archive.
# -z: gzip compression, -c: create, -f: specify filename
tar -zcf "$ARCHIVE_NAME" -C "$SOURCE_DIR" .

echo "Backup saved: $ARCHIVE_NAME"

Running the above produces the following output:

$ ./backup_logs.sh /var/log /backup/logs
Backup saved: /backup/logs/logs_20240801_120000.tar.gz

Using commented-out code to manage debug output.

comment_debug.sh

#!/bin/bash
# A script that processes a list of files.
# During debugging, use comment-out to inspect intermediate values.

TARGET_DIR="${1:-.}" # use the current directory if no argument is provided

count=0
total_size=0

for file in "$TARGET_DIR"/*; do
	[ -f "$file" ] || continue # skip anything that is not a regular file

	size=$(wc -c < "$file")
	# Debug: check the size of each file (remove after verification)
	# echo "DEBUG: file=$file size=$size"

	count=$((count + 1))
	total_size=$((total_size + size))
done

# TODO: add logic to separately list large files (over 1 MB)
echo "Files: $count"
echo "Total size: ${total_size} bytes"

Running the above produces the following output:

$ ./comment_debug.sh /etc
Files: 42
Total size: 102400 bytes

Shell script comments consist of only one type: the single-line comment starting with #. There is no dedicated block comment syntax; to comment out multiple lines, add # to the beginning of each line.

The shebang line (#!/bin/bash, etc.) at the top of a file also starts with #, but it serves a different role — it is the interpreter specification that the kernel reads. The shebang line must be written on the very first line of the file. Writing it on any other line causes the kernel to ignore it and treat it as a plain comment.

It is a common convention to place a comment block at the top of a script summarizing its purpose, usage, arguments, and dependencies. Comments are most useful when they explain "why" rather than "what." There is no need to keep deleted code or change history in comments — those are tracked by version control (git).

Placing the shebang line somewhere other than line 1

The shebang line (#!/bin/bash, etc.) must be written on the first line of the file. When the kernel executes a script, it checks the first two bytes (#!) to determine the interpreter. If the shebang is on any other line, it is ignored.

shebang_ng.sh

# This script performs a backup
#!/bin/bash # shebang on line 2 is not recognized by the kernel

echo "backup start"

Running the above produces the following output:

chmod +x shebang_ng.sh
./shebang_ng.sh
./shebang_ng.sh: line 1: This script performs a backup: command not found

After fixing:

shebang_ok.sh

#!/bin/bash
# This script performs a backup

echo "backup start"

Running the above produces the following output:

chmod +x shebang_ok.sh
./shebang_ok.sh
backup start

No space after #

Writing #text without a space still works, but most coding conventions recommend writing # text with a single space after #. Static analysis tools such as ShellCheck also assume this style.