Why I Oppose Writing Only “Why” in Code Comments

I am a strong advocate of writing comments, but I disagree with the popular view that comments should only explain why (Why) and never what (What).

When the code itself is relatively clear, both the "what" and the "why" should be documented. This is especially important for business logic, where describing the overall process (What) is crucial.

For example, consider the following method that creates an order:

public void createOrder() {
    // 1. Validate order parameters
    validate();
    // 2. Create order
    create();
    // 3. Split order by supplier code
    splitOrder();
    // 4. Publish order‑created event
    publishEvent();
}

The four inline comments do not explain implementation details; they simply state the business steps, allowing a reader to grasp the entire workflow at a glance before diving into each method’s internals, thus reducing reading effort.

Some may argue that a well‑named method makes comments redundant. While good naming is essential, it is often insufficient. After weeks or months, developers may struggle to recall the full business flow from the method name alone. Concise flow comments help retain that context.

Conversely, over‑commenting messy code with dozens of lines that merely restate obvious statements adds no value. For instance:

// Get user
User user = getUser();
// Check if user is null
if (user == null) {
    ...
}

When the code is already clear, extra comments are unnecessary; the focus should be on writing clean code rather than compensating with excessive commentary.

In my view, high‑quality business code needs only two kinds of comments:

Core business‑process comments : describe each step (what) and the overall flow, providing the highest reading value.

Decision‑explanation comments : explain why a particular approach was chosen (e.g., why not query the database directly, why a lock is required, why caching is used instead of real‑time calculation, why two transactions cannot be merged).

Both the process (What) and the rationale (Why) are important: the former determines whether others can quickly understand the business, and the latter influences whether they feel confident modifying the code.

Therefore, if the code is clear, comments should cover only two scenarios: the core business flow and the key design decisions behind it. Anything beyond that is unnecessary. Comments are meant to lower the cost of reading, not to replace the code itself. Well‑written code with appropriately scoped comments is truly maintainable.