Understanding the Use of Indentation
As you work through the examples in this book, you see that certain lines are indented. In fact, the examples also provide a fair amount of white space (such as extra lines between lines of code). Python ignores any indentation in your application. The main reason to add indentation is to provide visual cues about your code. In the same way that indentation is used for book outlines, indentation in code shows the relationships between various code elements.
The various uses of indentation will become more familiar as you work your way through the examples in the book. However, it’s important to know at the outset why indentation is used and how it gets put in place. So, it’s time for another example. The following steps help you create a new example that uses indentation to make the relationship between application elements a lot more apparent and easier to figure out later.
- Choose File➪New
IDLE creates a new Edit window for you.
- Type print(“This is a really long line of text that will ” +.
You see the text displayed normally onscreen, just as you expect. The plus sign (+) tells Python that there is additional text to display. Adding text from multiple lines together into a single long piece of text is called concatenation. You learn more about using this feature later in the book, so you don’t need to worry about it now.
3es. sPErnter.
The insertion point doesn’t go back to the beginning of the line, as you might expect. Instead, it ends up directly under the first double quote,
as shown in Figure 4-18. This feature is called automatic indention and it’s one of the features that differentiates a regular text editor from one designed to write code.
- Type “appear on multiple lines in the source code ”) and press Enter.
Notice that the insertion point goes back to the beginning of the line. When IDLE senses that you have reached the end of the code, it auto- matically outdents the text to its original position.
- Choose File➪
You see the Save As dialog box.
- Type py in the File Name field and click Save to save it.
- Choose Run➪Run
A new Python Shell window opens with the text displayed. Even though the text appears on multiple lines in the source code file, it appears on just one line in the output, as shown in Figure 4-19.
Figure 4-18:
The Edit window automati cally indents some types
of text.
Figure 4-19: Use concat enation to make mul tiple lines of text appear on a single line in the output.
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.