Imagine looking at code you wrote six months ago. You know it works, but you have no idea why you wrote it a certain way or what a specific, complex line is supposed to do. This is a common problem, and Python has a simple, elegant solution: comments.
In Post #6, we learned the strict syntax rules that Python enforces. Now, we’ll learn how to write text that Python completely ignores, but which is invaluable for human readers. This post will teach you how to write effective comments to make your code clear, maintainable, and easy to understand.
What are Comments and Why Do We Need Them?
A comment is a line of text in your Python script that is completely ignored by the interpreter when the code is run. Its sole purpose is to be read by humans to provide context and explanation.
Good comments are crucial for several reasons:
- To Explain Complex Logic: They clarify the “why” behind a tricky piece of code, not just the “what.”
- To Leave Reminders: You can mark areas that need improvement or future work (e.g.,
# TODO: Optimize this section). - To Collaborate with Others: Comments help teammates understand your code, making it easier to work on projects together.
- To Temporarily Disable Code: This technique, known as “commenting out,” is a powerful tool for finding and fixing bugs.
The Single-Line Comment: Using the Hash Symbol (#)
The most common way to write a comment in Python is by using the hash symbol (#). Any text on a line that follows a # is treated as a comment and will be ignored.
You can use single-line comments in two ways.
1. Full-Line Comments
A comment can take up its own line. This is often used to introduce a block of code or provide a more general explanation.
# This script calculates the area of a rectangle.
# It assumes that length and width are positive numbers.
length = 10
width = 52. Inline Comments
A comment can also be placed at the end of a line of code. This is useful for adding a short, targeted note about that specific line.
area = length * width # Formula for the area of a rectangle
print(area)Multi-Line Comments and an Introduction to Docstrings
For longer, multi-line explanations, you can use triple quotes: either three double quotes (""") or three single quotes ('''). Anything enclosed within them is treated as a single string, and if not assigned to a name, Python effectively ignores it, making it a de facto multi-line comment.
"""
This is a multi-line comment.
It can span several lines and is useful for
providing a more detailed explanation of the code that follows.
"""
principal = 1000
rate = 0.05
time = 3An Important Note: While this syntax works perfectly for multi-line comments, its primary, official purpose in Python is to create docstrings (documentation strings). A docstring is a special comment placed at the very beginning of a module, function, or class to describe what it does. We will cover these in detail when we learn about functions, but it’s good to be aware of their main purpose now.
Best Practices for Writing Good Comments
Writing comments is easy, but writing good comments is a skill. Here are a few tips.
1. Don’t State the Obvious
Comments should add value. Commenting on code that is already self-explanatory just adds clutter.
- Bad:
x = 5 # Set x to 5 - Good:
x = 5 # The initial number of allowed attempts.
2. Explain the “Why,” Not Just the “What”
The code itself shows what is happening. Good comments explain why it’s happening.
- Bad:
speed = 9.81 # Set speed to 9.81 - Good:
speed = 9.81 # Gravitational constant in m/s^2
3. Keep Comments Updated
An out-of-date comment that contradicts the code is worse than no comment at all. If you change your code, make sure you update the comments that describe it.
4. Use Comments to Debug
If your code isn’t working, you can “comment out” lines to temporarily disable them. This is a great way to isolate the source of a problem.
print("Starting the program...")
# problematic_function() # Temporarily disabled to find the bug
print("Program finished.")What’s Next?
Comments are a conversation with your future self and your collaborators. Writing clear, concise, and helpful comments is a hallmark of a thoughtful and professional developer.
Now that we know how to write code Python executes and notes that it ignores, it’s time to learn how to store and manage data within our programs. In Post #8, we will dive into one of the most fundamental concepts in all of programming: variables.
Author
Experienced Cloud & DevOps Engineer with hands-on experience in AWS, GCP, Terraform, Ansible, ELK, Docker, Git, GitLab, Python, PowerShell, Shell, and theoretical knowledge on Azure, Kubernetes & Jenkins. In my free time, I write blogs on ckdbtech.com