Comments in Python
Why Use Comments in Code
In Python and programming in general, we comment code to provide context. Sometimes, we'll have to write elaborate sections and understand the purpose and logic behind them. With proper commenting, we can greatly improve the experience for both us and our collaborators, and introduce higher maintainability to our projects.
So, let's dive into the basic syntax of Python comments.
Comment Syntax in Python
We should keep the comments closely tied to the code they describe. Logically, they should have the same indentation with the code when they're positioned above it. There are some caveats to this, which we'll cover in our subsequent sections.
Notice the hash mark (#) followed by a space and the comment text. The interpreter will ignore any text that appears after the mark on the line.
# Create a new variable
website_name = "Web Reference"
# Print the value
print(website_name)
Inline comments, which appear on the same line as the code, should be used sparingly as they can quickly clutter our code and make it harder to read and understand.
x = 7 # This is an inline comment
Multiline Comments in Python
While Python does not have an official way to write multiline comments, there are two common methods that we can leverage. The first method involves using multiple hash marks on subsequent lines.
Block Comments
Block comments span multiple lines and are useful for providing a more in-depth explanation of a section of code.
# This is a block comment
# that spans multiple lines
# and provides a more detailed explanation of the code
The second method involves wrapping the comment in triple quotes, either single (''' ), or double ("""). Technically, this is a string, and if you already had the hunch, you're right on the mark. It isn't considered a comment but it serves the purpose of one.
"""
This is a multiline
comment using triple quotes
which is technically a string
also a docstring in certain cases
"""
However, there's a catch we should be aware of. These strings are ignored during runtime unless they appear at specific locations. If they're present as the initial lines of function declarations, classes, or modules, they become a docstring which is linked to that specific object.
def say_hello():
"""
This is a docstring that serves as a multiline comment.
It provides information about the 'say_hello' function.
"""
print("Hello!")
Now, the block of text between the triple quotes serves as a docstring, because it appears at the beginning of the say_hello function declaration, and is linked to the say_hello object.
Python Comment Usage and Best Practices
As a basic rule of thumb, it's advisable to adhere to the PEP guidelines and limit our line usage to a maximum of 79 characters. For longer blocks of text in comments or docstrings, the line length should be limited to 72 characters — after all, the main focus should be on our code.
Generally, we should practice the DRY (Don't Repeat Yourself) principle to avoid repeating information that's already evident or easily inferred. Also, we shouldn't overuse them. Comments can be invaluable but if rely too much on them, then the problem probably lies in writing poor code.
Commenting vs. Documenting
We already understand the usefulness of comments. They're typically brief and descriptive and provide much-needed context for a developer's personal and collaborative use.
Documenting, on the other hand, is mostly intended for end users and is typically more verbose and instructional. When documenting code, it's crucial to provide clear explanations that are comprehensible even for someone with little to no prior knowledge of the specific technology. You can find more context on this in our additional resources.