Up to this point, we’ve examined how Python interprets tokens, reserves keywords, and binds identifiers to objects. That entire layer focused on how the interpreter understands your program. But real software is not maintained by interpreters.It is maintained by humans.This is where comments and documentation become part of engineering discipline.
A Python program must satisfy two audiences: the interpreter and the developer. The interpreter needs syntactic correctness. Developers need clarity of intent. Comments and documentation exist for the second audience. They do not change how Python executes code. They change how humans understand it. And in long-lived systems, understanding is more valuable than cleverness.
Why Comments Exist
A comment in Python begins with the # symbol. Everything after it on the same line is ignored by the interpreter.
total = price * quantity # Calculate total before discountFrom Python’s perspective, that comment does not exist. It is stripped during the reading stage. But from a developer’s perspective, it may explain why the calculation is happening at that point in the program.
However, advanced developers follow an important rule:
Comments should explain why, not what.
Writing this:
total = price * quantity # Multiply price and quantityadds no value. The code already states that clearly.
But writing:
# Business rule: total must be calculated before discount logic
total = price * quantityexplains reasoning. It captures intent. Intent is what disappears fastest over time.
Comments are most useful when the code alone cannot communicate the decision behind it.
When Code Should Replace Comments
If a comment constantly explains what the code is doing, that is often a sign that the code itself needs improvement.
Consider:
# Check if user is active and admin
if user.is_active and user.role == "admin":This comment is redundant. A better solution is clearer abstraction:
if user.is_admin():Readable code reduces the need for explanatory comments. Good naming and clean structure are the first layer of clarity. Comments should support clarity, not compensate for poor design.
Block Comments and Context
Sometimes a section of code requires context. In those cases, block comments placed above the code are appropriate.
# Apply fallback mechanism for legacy API compatibility
if response.status_code == 404:
handle_legacy_route()Block comments help explain assumptions, temporary workarounds, or design trade-offs. They are especially valuable when interacting with external systems or maintaining backward compatibility. But discipline is essential. Outdated comments are worse than no comments. They create misinformation. A comment must be maintained with the same seriousness as code.
Docstrings — Structured Documentation Inside Code
Unlike regular comments, docstrings are string literals placed at the beginning of modules, classes, or functions. They are not ignored. Python stores them as metadata and makes them accessible at runtime.
def calculate_total(price, quantity):
"""
Calculate the total cost before applying discounts.
Args:
price (float): Price per unit.
quantity (int): Number of units.
Returns:
float: Total calculated amount.
"""
return price * quantityDocstrings define contracts. They describe expected inputs, outputs, and behavior. Tools such as help(), IDEs, and documentation generators rely on them. Docstrings are not casual notes. They are part of the public interface of a function or class. When documentation is clear, integration becomes easier. When it is vague or missing, confusion multiplies.
Module-Level Documentation
Entire modules can begin with a docstring that explains their responsibility.
"""
Order processing module.
Handles order creation, discount strategies, and total calculation logic.
"""In large projects with dozens of modules, this kind of documentation prevents architectural confusion. It clarifies boundaries and purpose. Documentation at this level reinforces design.
Documentation as a Design Tool
At an advanced level, writing documentation is not an afterthought. It is a design exercise.
When you write a docstring, you are forced to answer:
- What does this component do?
- What does it expect?
- What does it guarantee?
- What does it not guarantee?
If you struggle to document something clearly, that often indicates weak abstraction or unclear responsibility. Clear documentation is often evidence of clear design.
Comments and Tooling
Modern development tools interact heavily with documentation. Static analyzers, documentation generators, and type checkers all benefit from well-written docstrings.
For example, API documentation frameworks automatically extract function and class documentation. This means your internal documentation can become public documentation with minimal additional effort.
Good documentation reduces onboarding time, debugging cost, and architectural misunderstanding. It transforms a codebase from a collection of files into a navigable system.
Why Comments and Documentation Matter
In small scripts, documentation may feel optional. In production systems, it is essential.
Software often lives longer than its original author’s memory of it. Without documentation, decisions become mysterious. With documentation, reasoning is preserved.
- Comments capture intent.
- Docstrings define contracts.
- Module documentation clarifies boundaries.
- Together, they form the human layer of software engineering.
- Code executes for machines.
- Documentation sustains collaboration.
What Comes Next
Now that you understand how Python reads code and how developers communicate intent within it, the next step is to examine how Python defines structure using whitespace.
In the next article, you will explore Indentation and Code Blocks in Python, and how Python uses indentation as part of its grammar to define execution boundaries. Because once code is readable to humans, it must also be structurally precise for the interpreter. And in Python, structure is visible — not hidden behind braces.
