Lesson 7	Including comments in shell scripts
Objective	Explain the importance of comments in a shell script.

Including Comments in Shell Scripts

The two commands you have just learned, echo and read, are straightforward. But as scripts become longer and more complex, the meaning of commands is sometimes difficult to determine. This is especially true when:

You wrote the shell script months (or years) ago and cannot recall exactly how you did things
Someone else wrote a shell script and you need to update it or use it as the basis for another project
You want to improve the appearance of the shell script to make it easier to follow what’s going on in it

When to use Comments: For both of these reasons, comments are added to scripts to explain what each command or section of commands does. Comments are not interpreted by the shell: they are ignored. So adding many comments does not affect the speed of your shell script. Shell script comments generally should not explain the meaning of the commands themselves. You will become very familiar with the commands. Rather, comments should explain why you use a certain command or what it accomplishes in the script overall. For example, a poor comment would be:
```
Test the value of the variable.
```
If someone reads your script, they might think:
```
“Yes, I can see that, but why are you testing it?”
```
A better comment would be:
```
Test whether flight number is within a valid range.
```

How to add comments in Shell Scripts

A comment in a script is any line that begins with a hash mark (also called a pound sign): #. When the shell finds a # character, everything until the end of the line is ignored. In a large shell script, a block of comment lines are often used to introduce a section of the script, something like this:

#===================================
# Test flight numbers stored in travel records
# to determine validity. Base on the airline
# place records in appropriate database directory
#
# Created 12 Nov 2009; Modified 20 Jan 2010;
# N. Wells for FarAway.com
#===================================

The exception to a hash mark being a comment is when the first line of a shell script begins with #! to indicate the path to the interpreter, such as #!/bin/sh. This was described in an earlier lesson in this module.
In addition to using comment statements in scripts, you can make your script self-commenting by using descriptive names for variables. The following series of images shows how a simple script is executed, skipping over comments that describe the function of each section of the script.

Self-commenting Code

As you learn about different shell scripting elements, you can help make your code easy to understand by using variable names and function names that are descriptive. Do not hesitate to use names longer than just three to five characters. For example, the variable name count may do the job, but using a variable name of flight_number is much more helpful. Functions (which you will learn about later in the course) enable you to name an entire block of statements and refer to them by one name. Make that name as descriptive as possible. As you write more complex scripts, establish a pattern of naming variables, functions, and even shell script files. Because UNIX is case sensitive, names such as flightnumber, FlightNumber, and FLIGHTNUMBER are all different. Choose one method of naming items using embedded capital letters, all lowercase, with an underscore between words, or something similar. This will help you keep track of the words you have used in your shell scripts and avoid errors as you create larger projects.

Environment variables

There are many environment variables that change the way the system works. You can set these interactively, or more usefully in your ~/.bashrc file.

PS1 Prompt
PS1 is the basic shell prompt; you can customize this. The default for bash is \s-\v\$, or 'shellversion-dollar' for example, bash-4.1$. Numerous settings are available, see the Prompting section of the bash man page for the full list. A common value for PS1 is
```
\u@\h:\w$ 
```
this displays the login name, the server name, and the current working directory. The following example:
```
steve@goldie:/var/log$
```
shows that you are logged in to the server 'goldie' as the user 'steve,' and are currently in the
```
/var/log directory.
```
In Debian, the default ~/.bashrc allows for color in the PS1 prompt, but it also comments that the focus in a terminal window should be on the output of commands, not on the prompt. You can uncomment the force_color_prompt=yes line in that file if you really do want a color prompt.

PATH environment variable

You can set your PATH environment variable to tell the shell where to search for programs (and scripts) to be run. The main system commands are in /bin, /usr/bin, /sbin, and /usr/sbin, but you may have your own scripts in $HOME/bin, $HOME/scripts, /usr/local/bin, or elsewhere. Append these to the PATH so that they will be found by the shell even when you are not in that directory:

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

Without the PATH, you will need to provide an explicit path (either absolute or relative) to the command.
For example:

$ myscript.sh
bash: myscript.sh: command not found
$ /home/steve/bin/myscript.sh
... or:
$ cd /home/steve/bin
$ ./myscript.sh

Comments in a Shell Script

#!/bin/sh #================================= # This sample script contains only # a few commands # ================================ # Request username and record for later use echo Please enter your name: read MYNAME # Confirm that the name is correct before proceeding echo Is $MYNAME the correct name? read ANSWER if[ANSWER ="Y"] then
1) The first line of the script names the command interpreter.

3) All comment lines are skipped; the first line to be executed is the line with the echo command.

4) The next line executed is the line containing the read command.

5) Blank lines and comments are skipped; the next echo command is then executed.

#!/bin/sh #================================= # This sample script contains only # a few commands # ================================ # Request username and record for later use echo Please enter your name: read MYNAME
6) The next read command is executed, and the script proceeds with other commands, skipping all comment lines.

You can use sed command to comment lines between two line numbers. Example:

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

Above code will comment the code between line 10&30. The next lesson describes how to set a shell script file’s permissions to allow it to be executed.