Comments - KodeKloud

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:

Field	Purpose
Shebang	Defines the interpreter (`#!/usr/bin/env bash`)
Summary	One-line description of the script’s functionality
Usage	How to invoke the script, including any flags/options
Exit Codes	List of possible exit codes and their meanings
Author	Name 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 <your.email@example.com>

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