Structuring Code for Readability

Comments become increasingly useful as complexity grows because the code may show the operations clearly while hiding the reasoning, constraints, or context behind those operations.

Programming

When Readability Changes

A short program with only a few lines is often understandable at a glance. You can see what each statement does and follow the logic without much effort. As a program grows larger and more complex, that quick understanding becomes harder. The density of formal language increases: more keywords, operators, and function calls compete for your attention. At that point, a reader needs help understanding not only what the code does, but also why it was written that way.

What changes when a small, simple program becomes larger and denser?

Key point

Comments become increasingly useful as complexity grows because the code may show the operations clearly while hiding the reasoning, constraints, or context behind those operations.

Trace the Reader’s Questions

When reading code, a learner or maintainer usually encounters two different questions. The first is, “What is this code doing?” The code itself often answers that question. The second is, “Why was it written this way?” The answer to that question may not be visible in the keywords, operators, or function calls. Effective comments focus on that missing context.

How does a comment that restates the code differ from a comment that explains the reasoning behind it?

Comment focus	What it contributes	Typical value
What	Describes the operation already visible in the code	Often redundant
Why	Explains context, reasoning, or a non-obvious decision	Adds information the code alone may not provide

Useful comments add context that readers cannot easily infer from the code alone.

A Discount Decision

Worked example

Replacing a Restatement with Reasoning

Choose a useful comment for a discount applied to qualifying orders.

1
Read the visible operation
The code can show that a discount is being calculated or applied. A comment saying “Calculate the discount” repeats that visible operation.
2
Ask what the code does not reveal
The reader may not know why the discount exists, why the threshold is 100 dollars, or why the rate is 10 percent.
3
Record the business reasoning
A useful comment explains that the 10 percent discount applies to orders over 100 dollars to encourage bulk purchases.

Result

The meaningful comment explains the business logic behind the decision instead of repeating the calculation.

python

if order_total > 100:
    # Apply a 10% discount for orders over 100 dollars to encourage bulk purchases.
    discount_rate = 0.10
    final_total = order_total * (1 - discount_rate)

if order_total > 100:
    # Apply a 10% discount for orders over 100 dollars to encourage bulk purchases.
    discount_rate = 0.10
    final_total = order_total * (1 - discount_rate)

Output

The code expresses the condition and calculation. The comment supplies the business reason for the threshold and discount.

Where Explanation Matters

Comments shine when the code contains a choice that is not obvious from its surface form. Focus explanations on non-obvious features, business logic, constraints, and reasoning. This includes a non-obvious design choice, a workaround for a limitation or bug, a tricky algorithm, or a specific requirement that a reader might not immediately recognize.

A non-obvious choice: explain why this approach was selected.
A limitation or bug workaround: explain the problem that required the workaround.
A tricky algorithm: explain the reasoning a reader cannot easily infer from the implementation.
A specific requirement: explain the external rule or constraint that shaped the code.
Business logic: explain the purpose behind a threshold, rate, or decision.

python

# Redundant: the condition already shows that the value is checked.
if order_total > 100:
    # Check whether the order total is greater than 100.
    apply_discount = True

# More useful: the comment records the business reason.
if order_total > 100:
    # The threshold supports the bulk-purchase pricing requirement.
    apply_discount = True

# Redundant: the condition already shows that the value is checked.
if order_total > 100:
    # Check whether the order total is greater than 100.
    apply_discount = True

# More useful: the comment records the business reason.
if order_total > 100:
    # The threshold supports the bulk-purchase pricing requirement.
    apply_discount = True

The first comment adds no information because the condition already shows what is being checked. The second comment records a reason that is not contained in the condition itself. The exact wording of a useful comment depends on the decision being documented, but its role is consistent: it preserves context that a reader cannot easily recover from the code alone.

Mistakes That Hide Meaning

Common mistake
Restating every statement in a comment
What it looks like
A condition is followed by a comment that repeats the condition in different words.
Why it fails
The code already communicates the operation, so the comment adds no value.
Do this instead
Remove the redundant comment or make the code clearer. Add a comment only if there is non-obvious reasoning to preserve.
Common mistake
Describing what while omitting why
What it looks like
The comment says that a discount is calculated but does not explain the qualifying threshold or business purpose.
Why it fails
The reader still cannot understand the decision behind the calculation.
Do this instead
Document the business logic, constraint, or reason that is not visible in the code.
Common mistake
Commenting obvious code while leaving unusual choices unexplained
What it looks like
A simple operation is carefully described, but a workaround for a limitation has no explanation.
Why it fails
The comment effort is directed away from the information readers are least able to infer.
Do this instead
Prioritize non-obvious features, workarounds, tricky algorithms, and specific requirements.
Common mistake
Using comments instead of clearer code
What it looks like
A confusing section receives several comments that describe its steps but do not improve the code’s clarity.
Why it fails
Redundant comments can accumulate without solving the underlying readability problem.
Do this instead
Replace redundant comments with clearer code where possible, and reserve comments for context and reasoning.

A Practical Comment Check

1
Read the code without the comment.
2
Identify what the code already makes obvious.
3
Ask whether the comment answers a why question.
4
Check whether it records business logic, a constraint, a non-obvious choice, or other context.
5
If it only repeats the code, delete it or rewrite the code to be clearer.
6
If it preserves reasoning that cannot be inferred easily, keep and refine it.

EASY

Consider this comment: “Set the discount rate to 10 percent.” Decide whether it is redundant or meaningful. Then rewrite it so that it explains the reasoning behind the rate, using the discount scenario from this article.

Hints

Ask whether the code already shows the value being assigned.
Look for the business purpose behind the discount.

Your attempt (not saved)

What do you think happens?

Which comment is more useful when the code already shows that a discount is being calculated?

Calculate the discount.
Apply a 10% discount for orders over 100 dollars to encourage bulk purchases.

Reveal answer

Answer:

Apply a 10% discount for orders over 100 dollars to encourage bulk purchases.

The first comment restates what the code does. The second explains the business reasoning and the condition behind the decision.

The Readability Principle

Readable code communicates its operations, while valuable comments preserve the reasoning that the operations cannot communicate by themselves. As programs grow denser and more complex, that distinction becomes increasingly important. Explain why a non-obvious choice was made, document business logic and constraints, and record context that future readers may not be able to infer. Avoid comments that merely repeat visible code, and improve the code itself when clarity is the better solution.

Key Takeaways

Larger programs become harder to read because their formal language becomes denser.
Comments are most valuable when they explain why code was written a particular way.
Comments that merely restate visible code logic are redundant.
Document non-obvious choices, business logic, constraints, workarounds, tricky algorithms, and specific requirements.
Before writing a comment, ask whether it answers a why question that the code alone cannot answer.

Related concepts

Naming Variables for Readability

More concepts starting with S

When Readability Changes

Trace the Reader’s Questions

A Discount Decision

Where Explanation Matters

Mistakes That Hide Meaning

A Practical Comment Check

The Readability Principle

Key Takeaways

Related Topics

Related concepts