Structuring Code for Readability

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.

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.

A Discount Decision

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)

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.

# 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

• Restating every statement in a comment

  The code already communicates the operation, so the comment adds no value.

  Fix: Remove the redundant comment or make the code clearer. Add a comment only if there is non-obvious reasoning to preserve.

• Describing what while omitting why

  The reader still cannot understand the decision behind the calculation.

  Fix: Document the business logic, constraint, or reason that is not visible in the code.

• Commenting obvious code while leaving unusual choices unexplained

  The comment effort is directed away from the information readers are least able to infer.

  Fix: Prioritize non-obvious features, workarounds, tricky algorithms, and specific requirements.

• Using comments instead of clearer code

  Redundant comments can accumulate without solving the underlying readability problem.

  Fix: 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.

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.