Adding Comments
People create notes for themselves all the time. When you need to buy gro- ceries, you look through your cabinets, determine what you need, and write it down on a list. When you get to the store, you review your list to remember what you need. Using notes comes in handy for all sorts of needs, such as tracking the course of a conversation between business partners or remem- bering the essential points of a lecture. Humans need notes to jog their mem- ories. Comments in source code are just another form of note. You add them to the code so that you can remember what task the code performs later. The following sections describe comments in more detail.
Understanding comments
Computers need some special way to determine that the text you’re writing is a comment, not code to execute. Python provides two methods of defining text as a comment and not as code. The first method is the single-line com- ment. It uses the number sign (#), like this:
A single-line comment can appear on a line by itself or it can appear after executable code. It appears on only one line. You typically use a single-line comment for short descriptive text, such as an explanation of a particular bit of code.
When you need to create a longer comment, you use a multiline comment. A multiline comment both starts and ends with three double quotes (“””), like this:
Everything between the two sets of triple double quotes is considered a com- ment. You typically use multiline comments for longer explanations of who created an application, why it was created, and what tasks it performs. Of course, there aren’t any hard rules on precisely how you use comments. The main goal is to tell the computer precisely what is and isn’t a comment so that it doesn’t become confused.
Even though single-line and multiline comments are both comments, the IDLE editor makes it easy to tell the difference between the two. When you’re using the default color scheme, single-line comments show up in red text, while multiline comments show up in green text. Python doesn’t care about the col- oration; it’s only there to help you as the developer.
Using comments to leave yourself reminders
A lot of people don’t really understand comments — they don’t quite know what to do with notes in code. Keep in mind that you might write a piece of code today and then not look at it for years. You need notes to jog your memory so that you remember what task the code performs and why you wrote it. In fact, here are some common reasons to use comments in your code:
- Reminding yourself about what the code does and why you wrote it
- Telling others how to maintain your code
- Making your code accessible to other developers
- Listing ideas for future updates
- Providing a list of documentation sources you used to write the code
- Maintaining a list of improvements you’ve made
You can use comments in a lot of other ways, too, but these are the most common ways. Look at the way comments are used in the examples in the book, especially as you get to later chapters where the code becomes more complex. As your code becomes more complex, you need to add more com- ments and make the comments pertinent to what you need to remember about it.
Using comments to keep code from executing
Developers also sometimes use the commenting feature to keep lines of code from executing (referred to as commenting out). You might need to do this in order to determine whether a line of code is causing your application to fail. In fact, it’s such a common and useful way to work with code that a technique for adding this sort of comment is built right in to IDLE. Here’s an example of
how this feature works. Say that you have an application like the one shown in Figure 4-20 (found in the Comments.py file provided as part of the down- loadable source code).
Figure 4-20: Sometimes developers
need to comment out lines of
code.
You might want to comment out the line that reads print(“This code is commented out.”). To make this happen, place the insertion point at the beginning of the line, or simply select the entire line, and choose
Format➪Comment Out Region. IDLE then adds a single-line comment to the code, as shown in Figure 4-21. Notice that this single-line comment uses two number signs (##) to differentiate it from a single-line comment you create by hand.
Figure 4-21: Comment out any code you don’t want Python to execute.
Of course, you don’t know yet whether the commenting has worked. Save the file to disk and then choose Run➪Run Module. You see a new Python Shell window open with just a single line of output, as shown in Figure 4-22. So, the first print() command, which isn’t commented out, executes just fine, but the second one doesn’t.
Figure 4-22: Commented out lines of code don’t execute.
To add the code back into the application, place the insertion point at the begin- ning of the line, or highlight the entire line, and choose Format➪Uncomment Region. IDLE removes the comment that it added earlier. Save the file and then
choose Run➪Run Module to see the result. This time, you see both print()
commands execute, as shown in Figure 4-23.
Figure 4-23:
Both print() commands execute when nei ther is com mented out.
You can comment out multiple lines of code at once by highlighting all of the lines and choosing Format➪Comment Out Region. Likewise, you can uncom- ment out multiple lines of code by highlighting all the lines and choosing Format➪Uncomment Region. It isn’t necessary to comment out or uncomment out one line at a time unless you have just one line of code to check.