Code Style and Conventions

Redundant comments restate what the code already shows; useful comments add context, meaning, or reasoning that the syntax cannot express.

Programming

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.

Key point

Useful comments explain the why: intent, assumptions, domain meaning, units, or reasoning. Redundant comments merely translate visible syntax into English.

Read the Code Before the Comment

What do you think happens?

Which comment adds more information to this assignment?

v = 5 # Set v to 5
v = 5 # Velocity in meters per second
Both comments add the same useful information

Reveal answer

Answer:

v = 5 # Velocity in meters per second

The first comment repeats the assignment that the code already displays. The second comment gives v a domain meaning and states its units, which the assignment syntax cannot express.

What does the code already communicate, and what additional intent, assumption, or domain meaning does a useful comment add?

Comment type	What the reader learns	Value
Redundant	What the syntax already shows	Adds no new insight
Useful	Intent, assumption, domain meaning, units, or reasoning	Explains information the syntax cannot express

A comment is useful when its information cannot be recovered directly from the surrounding code.

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.

When does improving a variable name make a comment unnecessary, and when is a comment still needed to explain meaning the name cannot convey?

python

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

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.

Before

tax_rate = 0.20  # Assumes the current standard tax rate

The value and its stated assumption agree.

After

tax_rate = 0.15  # Assumes the current standard tax rate

The value changed, so the comment must be checked and updated if the assumption no longer matches.

Key point

Comment maintenance is part of code maintenance. A comment that contradicts the code can send a reader toward the wrong interpretation.

Mistakes Beginners Make

Common mistake
Restating every operation
What it looks like
```
total = price + tax  # Add price and tax
```
Why it fails
The expression already displays the addition. The comment adds no information about the problem or the reason for the calculation.
Do this instead
Comment only if the calculation has context that the expression cannot show, such as a domain rule or an assumption.
Common mistake
Using a comment instead of a meaningful name
What it looks like
```
v = 5  # Velocity in meters per second
```
Why it fails
The comment supplies useful context, but the short name may still make later expressions harder to understand.
Do this instead
Use a clearer name when it improves readability, and retain a comment for information such as units that the name cannot conveniently express.
Common mistake
Making every variable name extremely long
What it looks like
```
total_price_including_current_standard_tax_rate = subtotal * (1 + tax_rate)
```
Why it fails
Very long names can make a complex expression visually dense and harder to parse.
Do this instead
Balance clarity with brevity. A concise name plus a clear context comment can be easier to read than a wall of text.
Common mistake
Leaving an outdated comment unchanged
What it looks like
```
tax_rate = 0.15  # Assumes the current standard tax rate
```
Why it fails
The code may no longer match the assumption described by the comment.
Do this instead
Review comments whenever the related code changes, and update or remove comments that are no longer accurate.

Comment Review Practice

MEDIUM

Review this small piece of code. Decide which comments are redundant, which are useful, and whether any variable name should change. Then rewrite the comments so they provide context without repeating the visible operations.

Hints

Ask what a reader can already learn directly from the operators and assignments.
Look for domain meaning, units, assumptions, or reasoning that the syntax does not show.
Check whether a shorter name would make the expression easier to read without hiding its meaning.

Your attempt (not saved)

python

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

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

Worked example

A comment audit

Improve the example by keeping comments that add context and removing comments that only translate syntax.

1
Inspect the first line
The assignment v = 5 already shows that 5 is assigned to v. The comment repeats the code, so it is redundant.
2
Inspect the second line
The expression already shows multiplication between two values. The comment is redundant unless the calculation has a domain-specific reason that is not visible here.
3
Inspect the third line
The expression shows that tax_rate is used, but the comment identifies an assumption about that rate. That context may help a reader understand when the calculation must be reviewed.
4
Improve the names
If v represents velocity, a descriptive name can communicate that role more directly. Names such as price and quantity already communicate their roles in the calculation.

Result

Keep a comment only where it adds meaning or an assumption that the code cannot express. Use variable names to communicate roles, while avoiding names so long that they obscure the expression.

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.

Key Takeaways

Redundant comments repeat information already visible in the code.
Useful comments explain intent, assumptions, domain meaning, units, or reasoning that syntax cannot express.
Descriptive variable names reduce the need for comments, but excessively long names can make expressions harder to read.
A concise name paired with a clear context comment can sometimes be more readable than a very long name.
Outdated comments are actively misleading, so comments must be reviewed when related code changes.

Related concepts

More concepts starting with C