Including Comments in Shell Scripts

The commands you have just learned (echo and read) are straightforward. But as scripts grow, the intent behind a sequence of commands can become unclear—especially when:

1. You revisit a script months (or years) later and no longer remember why it was written a certain way
2. Someone else wrote the script and you need to troubleshoot or extend it
3. You want the script to be readable enough that it can be safely maintained

What Good Comments Explain

• Comments should explain “why,” not “what.” The command itself usually explains what is happening; the comment should capture the reason or the larger purpose.
  
  A weak comment:
  

  Test the value of the variable.

  A stronger comment:
  

  Test whether flight number is within an allowed range before writing the record.

  
  Key rule: Comments are ignored by the shell, so adding helpful comments does not slow your script down.

In shell scripts, a comment begins with a hash mark: #. When the shell sees #, it ignores everything from that character to the end of the line.

A block of comment lines is often used to introduce a section or document metadata such as purpose and maintenance history:

#===================================
# Validate flight numbers in travel records
# Route records into the correct directory
#
# Created: 12 Nov 2009
# Modified: 20 Jan 2010
# Owner: N. Wells (FarAway.com)
#===================================

Important exception: The first line of a script may begin with #! (the “shebang”) to select the interpreter, for example:

#!/bin/sh

That line is not treated as a normal comment; it tells the OS which program should run the script.

Comments work best when combined with self-documenting code—choosing names that make the script readable without needing a comment on every line.

Use descriptive names for variables and (later) functions:

• Instead of count, consider flight_number or record_count.
• Choose a consistent naming style: lowercase_with_underscores, embeddedCaps, or ALL_CAPS. Then stick with it.
• Remember: Unix is case-sensitive (flightnumber, FlightNumber, and FLIGHTNUMBER are different names).

Modern best practice: Run a script linter such as ShellCheck during development. It catches common quoting bugs, unsafe tests, and portability problems that comments cannot prevent.

Two environment settings commonly affect the “feel” of a terminal session and how scripts are executed: your prompt (PS1) and your PATH.

PS1 controls the shell prompt displayed in your terminal. A common prompt format is:

\u@\h:\w$

Example:

steve@goldie:/var/log$

This shows the username, host, and current working directory. A readable prompt can reduce mistakes and make copy/pasted command examples easier to follow.

The PATH variable tells the shell where to search for programs (and scripts). System commands often live in directories such as /bin and /usr/bin. Your own scripts might live in $HOME/bin or /usr/local/bin.

You can extend your PATH like this:

PATH="${PATH}:${HOME}/bin"

Without PATH pointing to your script directory, you must run scripts using an explicit path:

$ myscript.sh
bash: myscript.sh: command not found

$ /home/steve/bin/myscript.sh
# or:
$ cd /home/steve/bin
$ ./myscript.sh

#!/bin/sh
#=================================
# Sample interactive script
# Purpose: collect a name and confirm it before continuing
#=================================

# Request username and record for later use
echo "Please enter your name:"
read -r MYNAME

# Confirm that the name is correct before proceeding
echo "Is $MYNAME the correct name? (Y/N)"
read -r ANSWER

if [ "$ANSWER" = "Y" ] || [ "$ANSWER" = "y" ]; then
  echo "Thanks. Continuing..."
else
  echo "Canceled."
fi

During development you may want to temporarily “comment out” a range of lines. One approach is to prefix lines with #. For example, this command prefixes lines 10 through 30 with #:

sed -i '10,30 s/^/#&/' mycode.sh

Use this carefully: it is best for quick experiments, but it is not a replacement for version control. In real projects, use Git branches or commits to toggle changes safely.

The next lesson describes how to set a shell script file’s permissions so it can be executed.