Code Style and Conventions

The Reader’s Missing Information

A comment earns its place when it tells a reader something the code cannot show by itself. Code usually communicates operations such as assigning a value, adding two numbers, or calling a function. It does not always communicate why the operation exists, what a value means in the real world, which assumption must remain true, or why one approach was chosen. The central question is therefore not whether a comment describes the code, but whether it supplies missing meaning.

Read the Code Before the Comment

The redundant version also creates a maintenance problem. If the code changes, the comment may need to change too, even though it never added useful information. Repeatedly seeing comments that say nothing new can also train readers to ignore comments. A useful comment should reduce the reader’s uncertainty rather than occupy space beside an already obvious operation.

Name Values Before Commenting

Variable names are one of the first tools for making code understandable. A descriptive name can communicate meaning directly and may remove the need for a comment. For example, a name that identifies a value as a velocity is more informative than a single-letter name. However, names have a readability cost: if every name is extremely long, a complex expression can become visually dense and difficult to parse.

tax_rate = 0.20
subtotal = price * quantity
total = subtotal * (1 + tax_rate)  # Assumes the current standard tax rate

In this example, the names price, quantity, subtotal, and total make the calculation easier to follow. The comment is still useful because it explains an assumption about the tax rate. The syntax shows how the value is used, but it does not explain why that rate is being applied or what outside condition could require changing it.

Keep Comments Synchronized

A useful comment must remain accurate as the code changes. An outdated comment is worse than no comment because it actively misleads the reader. When a value, calculation, assumption, or design choice changes, review nearby comments at the same time. Remove a comment if the code has become self-explanatory, and revise it if the underlying context has changed.

Mistakes Beginners Make

• Restating every operation

  The expression already displays the addition. The comment adds no information about the problem or the reason for the calculation.

  Fix: Comment only if the calculation has context that the expression cannot show, such as a domain rule or an assumption.

• Using a comment instead of a meaningful name

  The comment supplies useful context, but the short name may still make later expressions harder to understand.

  Fix: Use a clearer name when it improves readability, and retain a comment for information such as units that the name cannot conveniently express.

• Making every variable name extremely long

  Very long names can make a complex expression visually dense and harder to parse.

  Fix: Balance clarity with brevity. A concise name plus a clear context comment can be easier to read than a wall of text.

• Leaving an outdated comment unchanged

  The code may no longer match the assumption described by the comment.

  Fix: Review comments whenever the related code changes, and update or remove comments that are no longer accurate.

Comment Review Practice

v = 5  # Set v to 5
price = item_price * item_quantity  # Multiply item price by item quantity
total = price * (1 + tax_rate)  # Apply the current tax-rate assumption

Practical Review Questions

1. What does the code already make obvious?
2. Does the comment add intent, an assumption, domain meaning, units, or reasoning?
3. Would a better variable name communicate the value’s role more clearly?
4. Would a longer name make the surrounding expression harder to read?
5. Will the comment remain accurate if the related code changes?

Good commenting is selective. Let the code and variable names communicate what they can communicate clearly. Use comments to preserve the intent, assumptions, domain meaning, units, or reasoning that would otherwise require a reader to reverse-engineer the code. Finally, keep those comments synchronized with the implementation so they remain a reliable source of understanding.