Comments in Bash scripts are used to annotate and explain the code. They help make the script more understandable and maintainable. In Bash, there are several ways to include comments:

Single-Line Comments

Single-line comments in Bash begin with a # character. Everything on the line after the # is considered a comment and is ignored by the Bash interpreter.

1
2
3
4
#!/bin/bash

# This is a single-line comment
echo "Hello, World!"  # This is also a comment

Note: The top line of the script, which starts with a #, is interpreted as a shebang rather than a comment.

Multi-Line Comments

Bash does not have a built-in multi-line comment syntax like some other programming languages. However, you can use a : '...' or : "..." construct to create a block of comments. The : is a built-in command that does nothing, and the quoted text is ignored by the interpreter. This is a common workaround for multi-line comments.

1
2
3
4
5
: '
This is a multi-line comment.
It spans several lines.
It is ignored by the Bash interpreter.
'

Alternatively, you can use <<'COMMENT' with a here document to achieve a similar effect:
1
2
3
4
5
<<'COMMENT'
This is a multi-line comment.
It also spans multiple lines.
It is ignored by the Bash interpreter.
COMMENT

Documentation Comments

For more structured documentation, you can use comments to describe functions or sections of your script. This is useful for providing detailed descriptions, usage information, and examples.

1
2
3
4
5
6
7
8
9
10
11
12
#!/bin/bash

# Function to greet the user
# Usage: greet <name>
# Example: greet "Alice"
greet() {
  local name=$1
  echo "Hello, $name!"
}

# Main script execution
greet "Alice"

Best Practices for Using Comments

  • Be Clear and Concise: Comments should clearly explain what the code does, especially if the code is complex or not immediately obvious.
  • Keep Comments Updated: Ensure that comments are updated along with the code they describe. Outdated comments can be misleading.
  • Avoid Redundant Comments: Don’t state the obvious. For example, comments like # Increment i right next to i=$((i + 1)) can be redundant.
  • Use Comments for Sections: Use comments to divide the script into logical sections, which helps in readability.

Example Script with Comments:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#!/bin/bash

# Define variables
name="Alice"
age=30

# Output variable values
echo "Name: $name"  # Print the name
echo "Age: $age"    # Print the age

# Read user input
read -p "Enter your city: " city
echo "City: $city"

# Perform string replacement
new_name=${name/Alice/Bob}
echo "New Name: $new_name"