Comments
As a programmer, your goal should be to write code that’s clear on its own. However, sometimes you need to provide additional insight. That’s when comments come in handy. Comments consist of explanatory text that Python ignores when running your code.
Good comments capture context that doesn’t live naturally in the code itself, such as intent, assumptions, and surprising trade-offs. Because comments age along with the code, they can quickly become misleading if you write too many or let them drift out of date. Whenever possible, prefer clear naming and structure first, and use comments only when they add real value.
When you write comments, keep the following best practices in mind:
- Explain the why, not the what. Use comments to clarify intent, assumptions, and non-obvious decisions, rather than to narrate what each line of code does. If a comment merely restates what the code does, it isn’t necessary.
- Keep comments short, clear, and up to date. Write complete thoughts in simple language, and treat comments as part of the codebase that must be maintained. Outdated comments are misleading and confusing.
- Use the right type of comment. Prefer block comments to explain a complex section and inline comments for short clarifications on the same line.
- Avoid noisy or redundant comments. Don’t comment every line, don’t explain obvious operations, and don’t leave blocks of commented-out code. These patterns make it harder to discern which comments are relevant.
For documenting public behavior, inputs, outputs, and usage, rely primarily on docstrings. Inline comments are best reserved for explaining local decisions that aren’t obvious from the code itself.
Finally, you can check PEP 8’s section on comments to get familiar with the style guidelines for Python comments.
To see these ideas in practice, check out the following function, which finds the index of an item in a sequence:
🔴 Avoid this:
def find_index(sorted_items, target):
# Set left index
left = 0
# Set right index
right = len(sorted_items) - 1
# Loop while left is less than right
while left <= right:
# Compute middle
mid = (left + right) // 2
# Check if equal
if sorted_items[mid] == target:
# Return mid
return mid
# Check if less than target
elif sorted_items[mid] < target:
# Move left up
left = mid + 1
else:
# Move right down
right = mid - 1
# Return -1 if not found
return -1
This function works, but it includes comments on nearly every line. The comments restate what the code already makes clear, adding noise instead of clarity. Now consider an improved version with better comments.
✅ Favor this:
def find_index(sorted_items, target):
"""Return the index of target in sorted_items, or -1 if not found."""
left = 0
right = len(sorted_items) - 1
while left <= right:
mid = (left + right) // 2
value = sorted_items[mid]
if value == target:
return mid
# If target is larger, you can safely ignore the left half
if value < target:
left = mid + 1
# Otherwise, target must be in the left half (if present)
else:
right = mid - 1
return -1
In this version, the docstring summarizes the function’s purpose and behavior, while the inline comments explain why certain branches exist. The code remains readable on its own, and the comments add meaningful context instead of repetition. Note how thoughtful spacing and grouping also improve clarity.
Related Resources
Tutorial
Writing Comments in Python (Guide)
Learn how to write Python comments that are clean, concise, and useful. Quickly get up to speed on what the best practices are, which types of comments it's best to avoid, and how you can practice writing cleaner comments.
For additional information on related topics, take a look at the following resources:
