Formatting Scripts for Readability
Just as the development environment, IDLE, will help you as your Python scripts get larger, a few minor practices also will be helpful to you. Learn these tips early on, so they become habits as your Python skills grow (and as the length of your scripts grow!).
Long Print Lines
Occasionally you will have to display a very long output line using the print function, such as a paragraph of instructions for the script user. The problem with long output lines is that they make your script code hard to read and the logic behind the script harder to follow. Python is supposed to “fit in your brain.” The habit of breaking up long output lines will help you meet that goal. There are a couple of ways you can accomplish this.
The first way to break up a long output character line is to use something called string concatenation. String concatenation takes two or more strings of text and “glues” them together, so they become one text string. The “glue” in this method is the plus (+) symbol. However, to get this to work properly, you also need to use the backslash (\) to escape out of the print function’s normal behavior—putting a linefeed at a character string’s end. Thus, the two items you need are +\, as shown in Listing 4.10.
Listing 4.10 String Concatenation for Long Text Lines
>>> print("This is a really long line of text " +\ ... "that I need to display!") This is a really long line of text that I need to display! >>>
As Listing 4.10 shows, the two strings are concatenated and displayed as one string in the output. However, there is an even simpler and cleaner method of accomplishing this. You can forgo the +\ and simply keep each character string in its own sets of quotation marks. The character strings will be automatically concatenated by the print function! The print function handles this perfectly and is a lot cleaner looking. This method is demonstrated in Listing 4.11.
Listing 4.11 Combining for Long Text Lines
>>> print("This is a really long line of text " ... "that I need to display!") This is a really long line of text that I need to display! >>>
It is always a good rule to keep your Python syntax simple to provide better script readability. However, sometimes you need to use complex syntax. This is where comments will help you. No, not comments spoken aloud, like “I think this syntax is complicated!” We’re talking about comments that are embedded in your Python script.
In scripts, comments are notes from the Python script author. A comment’s purpose is to provide understanding of the script’s syntax and logic. The Python interpreter ignores any comments. However, comments are invaluable to humans who need to modify or debug scripts.
To add a comment to a script, you precede it with the pound or hash symbol (#). The Python interpreter ignores anything that follows the hash symbol.
For example, when you write a Python script, it is a good idea to insert comments that include your name, when you wrote the script, and the script’s purpose. Figure 4.2 shows an example. Some script writers believe in putting these comments at their script’s top, while others put them at the bottom. At the very least, if you include a comment with your name as the author in your script, when the script is shared with others, you will get credit for its writing.
Figure 4.2 Comments in a Python script.
You also can provide clarity by breaking up sections of your scripts using long lines of the # symbol. Figure 4.2 shows a long line of hash symbols used to separate the comment section from the main body of the script.
Finally, you can put comments at the end of a Python statement. Notice in Figure 4.2 that the print() statement is followed by the comment # Inserts a blank line in output. A comment placed at the statement’s end is called an end comment, and it provides clarity about that particular code line.
Those few simple tips will help improve your code’s readability. Putting these tips into practice will save you time as you write and modify Python scripts.