Skip to main content
Clear, concise comments make your shell scripts easier to maintain, understand, and extend. Follow these best practices to ensure your scripts are well-documented and self-explanatory.

​
Header Comment Structure

A standardized header typically includes:
FieldPurpose
ShebangDefines the interpreter (#!/usr/bin/env bash)
SummaryOne-line description of the script’s functionality
UsageHow to invoke the script, including any flags/options
Exit CodesList of possible exit codes and their meanings
AuthorName and contact information
With modern version control systems like Git, embedding a change history in comments is usually redundant.

​
Example Header

#!/usr/bin/env bash
#
# Script usage: Brief summary of the script’s purpose and how to invoke it.
# Exit codes: 0 = Success, 1 = General error, 2 = Missing arguments
# Author: Your Name <[email protected]>

​
Tips for Effective Comments

  • Keep lines under 80 characters for readability.
  • Write comments in complete sentences where clarity is needed.
  • Update comments whenever you modify related code blocks.
  • Avoid over-commenting trivial code—focus on intent, not implementation.

​
References

Watch Video