Documenting automated shell scripts with clear comments helps peer developers understand complex command flags, environment dependencies, and error recovery steps. This guide covers single-line # comments, shebang headers, and multi-line heredoc block comments in Bash.

Single-Line and Multi-Line Comment Examples

comments_demo.shbash
#!/usr/bin/env bash
# ==============================================================================
# Script Name: backup_db.sh
# Description: Performs nightly PostgreSQL database dump to local backup volume
# Author:      Lynxbee Engineering
# ==============================================================================
 
# 1. Single-line comment explaining the variable below
BACKUP_DIR="/var/backups/postgres" # Inline comment: Ensure 50GB disk space
 
# 2. Multi-line Heredoc Block Comment Trick (Ignored by Bash interpreter)
: << 'COMMENT_BLOCK'
The block of text inside here is completely ignored by the Bash execution engine.
It allows writing multi-paragraph technical documentation, changelogs, or temporarily
disabling large sections of shell code during local testing.
COMMENT_BLOCK
 
mkdir -p "${BACKUP_DIR}"