Writing Readable Code
A comment is text after the # symbol that Python ignores. It is a note 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.
- 1Brief clarification
Use an inline comment when the explanation belongs to one statement and can remain short.
- 2Larger explanation
Use a block comment when the reader needs context for a section or a decision that spans multiple lines.
- 3Reader 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 |
The strongest comments add information that is not obvious from the code itself.
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.
Common mistake Restating the code instead of explaining a reason
What it looks likeA comment says that a value is being assigned immediately beside an assignment.
Why it failsThe code already shows that operation, so the comment does not give the reader new information.
Do this insteadUse the comment to explain the decision, assumption, important detail, or problem behind the assignment when that context is not obvious.
Common mistake Writing a long explanation beside one simple statement
What it looks likeA brief clarification is expanded into a large comment that overwhelms the line it describes.
Why it failsThe comment makes a simple section harder to scan.
Do this insteadUse an inline comment for a brief clarification and reserve a block comment for a larger idea or complex decision.
Common mistake Leaving a comment inaccurate after changing code
What it looks likeThe code changes, but the explanation still describes the earlier decision.
Why it failsThe comment now misleads the reader instead of helping them understand the program.
Do this insteadKeep comments up to date when you change the code.
Common mistake Assuming comments execute
What it looks likeA learner expects text after # to affect the program.
Why it failsPython discards the # and everything after it through the end of the line.
Do this insteadTreat 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.
- 1Read the code first
Identify the operation that is already obvious from the line.
- 2Find 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.
- 3Choose the form
Use an inline comment for a short local clarification or a block comment for a broader explanation.
- 4Check 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
- 1Python comments begin with #, and Python ignores the symbol and everything after it on that line.
- 2The part before # is code; the part from # to the line end is a comment.
- 3Inline comments suit brief clarifications, while block comments suit larger ideas and complex decisions.
- 4Strong comments explain why code was chosen and document assumptions, important details, or problems being solved.
- 5Avoid 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.