Code Comments
Code comments are notes of explanation that document lines or sections of a program. Comments are part of the program, but the Python interpreter ignores them. They are intended for people who may be reading/modifying the source code in the future. In Python, you begin a comment with the # character. When the Python interpreter sees the # character, it ignores everything from that character to the end of the line.
Here’s an example:
|
1 2 3 4 |
# Display my address print("123 Anywhere St.") print("Toronto, Ontario") # I could have used 'The Six' instead print("A1B 2C3") |
Notice in the second last line I used what is called an end-of-line comment. These are used to explain the statement that appears on that line. While end-of-line comments are useful from time to time, generally full-line comments are preferable.
As a beginning programmer, you probably think comments are a waste of time since they don’t actually do anything, but trust me — they become more and more essential as your programs grow in complexity. I want to get you into the good habit of commenting as early as possible!
Style Rule #2: Code CommentsIt is considered good style to comment on tricky or clever parts of your code to make it easier for others (and even yourself) to read/understand it in the future. It’s important that comments accurately reflect the code that they explain. An incorrect comment is worse than none! Full-line comments (as opposed to end-of-line comments) are almost always the best choice as they are easier to read and don’t cause formatting problems when you print the code. A comment should always appear before the statement(s) it describes. |
Header Docstrings
Triple-quoted strings have another important use. Like # comments, they are useful in documenting the major features of your code, but unlike comments, they can be used by a program called pydoc to automatically generate online help for your program. When triple-quoted strings are used to document code in this way they are called docstrings in Python.
A header comment is a comment that appears at the top of a Python script and includes information about the author of the program, the date when it was last modified, and a general description of what the program does. Docstrings are ideally suited for header comments:
|
1 2 3 4 5 6 7 8 9 10 11 |
"""Author: Vik Twenty Date: September 24, 2021 Description: This program displays my physical mailing address. """ # Display my address print("123 Anywhere St.") print("Toronto, Ontario") # I could have used 'The Six' instead print("A1B 2C3") |
For now, just think of a docstring as a special kind of comment. You’ll appreciate why they are so powerful later when we get into more advanced material.
Style Rule #3: Header CommentsA header comment is a comment that appears at the top of a Python script. It is considered proper programming style to include information here about the author, a general description of what the program does, and the date it was last modified. In Python, a triple-quoted string called a docstring is used for header comments, not the # comment. We’ll see later that docstrings are very useful for automatically producing online help for our code. |
You’ll also note that in the example above, I’ve included a blank line between the docstring and the code comment. Blank lines are not important to the Python Interpreter, but using them makes the code easier to read.
Style Rule #4: Blank LinesUse blank lines to improve the readability of your code. Group related code together and separate sections with a blank line. |
You Try!
-
- Add the heading “1-7 Code Commenting” to your learning journal and answer the following questions:
- Why must all programs start with a docstring, and what should it contain?
- Why include code comments if the Python interpreter ignores them?
- Add the heading “1-7 Code Commenting” to your learning journal and answer the following questions: