Writing Readable Code
Comments are text after the # symbol that Python ignores; they are notes for readers, not executable code.
The Reader Behind the Code
Readable code has two audiences: Python and the people who read the program. Python needs executable instructions. People often need additional context, such as the reason for a decision, an assumption being made, or a problem the code is solving. Python comments provide that human context without becoming part of the program's execution.
A comment is text after the # symbol that Python ignores. It is a note for readers, not executable code.
What Python Reads
The # symbol marks the boundary between code and a comment on the same line. Everything before # is code that Python will execute. Everything from # through the end of that line is a comment that Python skips entirely.
The interpreter reads a line from left to right. When it encounters #, it discards everything from that character to the end of the line and moves to the next line. From the interpreter's perspective, the comment never existed. This is why adding or changing a comment does not change what the program does.
Two Comment Positions
An inline comment appears at the end of a line of code, after the # symbol. It is useful for a brief clarification about one statement.
A block comment occupies its own line or multiple lines, with each line beginning with #. It is better suited to a larger idea, a section of code, or a complex decision that spans multiple lines.
| Comment form | Position | Best use |
|---|---|---|
| Inline comment | At the end of a code line | A brief clarification about one statement |
| Block comment | On its own line or lines | A larger idea, section, or complex decision |
Both forms are valid; choose based on how much context the reader needs.
Choosing a Comment Form
A programmer needs to explain both a single unusual line and a larger decision spanning several lines.
Brief clarification: Use an inline comment when the explanation belongs to one statement and can remain short.
Larger explanation: Use a block comment when the reader needs context for a section or a decision that spans multiple lines.
Reader check: Place the explanation where the reader encounters the code it explains.
Inline comments suit local clarifications, while block comments suit broader explanations.
Document the Reason
Code usually shows how something works: the operations, conditions, and steps that Python performs. A useful comment adds the why. It can explain an assumption, an important decision, an important detail, or a problem the code is solving or overcoming.
| Comment focus | What it contributes | Typical value to the reader |
|---|---|---|
| How | Restates the visible operation | Often limited when the code is already clear |
| Why | Explains the reason for a choice | Preserves context that the code may not reveal |
| Assumption | Records what the code relies on being true | Helps a reader understand the conditions behind the solution |
| Problem | Identifies the issue being solved or overcome | Makes the purpose of an unusual approach clearer |
Generated example: A line that selects one of several possible values may be easy to read but still leave an important question unanswered: why was this value selected instead of another one? A useful comment would preserve the decision or assumption behind that choice rather than repeat the selection operation.
Helpful Notes and Clutter
Comments improve readability when they clarify code that would otherwise be difficult to understand. They reduce readability when they repeat what the code already says, appear everywhere without adding context, or become inaccurate after the code changes.
Restating the code instead of explaining a reason
The code already shows that operation, so the comment does not give the reader new information.
Fix:
Use the comment to explain the decision, assumption, important detail, or problem behind the assignment when that context is not obvious.Writing a long explanation beside one simple statement
The comment makes a simple section harder to scan.
Fix:
Use an inline comment for a brief clarification and reserve a block comment for a larger idea or complex decision.Leaving a comment inaccurate after changing code
The comment now misleads the reader instead of helping them understand the program.
Fix:
Keep comments up to date when you change the code.Assuming comments execute
Python discards the # and everything after it through the end of the line.
Fix:
Treat comments as notes for readers, not executable instructions.
Before keeping a comment, ask whether it tells the reader something the code does not. If it does not, clearer code structure may be more useful than another note.
Practice the Reader's View
For each proposed comment, decide whether it adds useful context, merely repeats the code, or should be rewritten. Then identify whether an inline comment or a block comment would fit better.
Hints
- Look for a reason, assumption, important detail, or problem that is not already visible.
- Use inline comments for brief clarifications about one statement.
- Use block comments for a larger idea, section, or complex decision.
Improving a Comment
A comment only repeats what a nearby line visibly does. Improve it without adding unnecessary detail.
Read the code first: Identify the operation that is already obvious from the line.
Find the missing context: Ask whether the reader needs to know why the operation was chosen, what assumption it relies on, or what problem it addresses.
Choose the form: Use an inline comment for a short local clarification or a block comment for a broader explanation.
Check future accuracy: Make sure the explanation will remain true when the code changes, or update it when the decision changes.
The improved comment should add non-obvious context rather than narrate an already visible operation.
Readable Code in Practice
- Python comments begin with #, and Python ignores the symbol and everything after it on that line.
- The part before # is code; the part from # to the line end is a comment.
- Inline comments suit brief clarifications, while block comments suit larger ideas and complex decisions.
- Strong comments explain why code was chosen and document assumptions, important details, or problems being solved.
- Avoid comments that repeat obvious code, clutter a section, or become inaccurate after changes.
Key Takeaways
- A Python comment is reader-oriented text beginning with # that the interpreter ignores.
- The # symbol separates executable code from the comment on the same line.
- Inline comments clarify one statement; block comments explain a broader idea or decision.
- Comments are most valuable when they explain why, record assumptions, preserve important decisions, or describe problems being solved.
- Readable code needs comments that add context without repeating the code or becoming outdated.