Maybe comments should explain 'what' (2017)

Debate over “Clean Code” / micro-method style

• Many commenters complain about the “every tiny thing in its own method/interface” style (associated with Clean Code), saying it harms readability: you must jump through many tiny functions/files to understand a simple sequential flow.
• Others note the book doesn’t literally say “one line per method” but does strongly push very short (2–3 line) functions, which some see as unreasonable when taken literally or applied dogmatically.
• Some engineers still like very small functions but criticize how that style is commonly implemented: too many classes, interfaces and indirection, inflated internal APIs, and “reuse” that rarely pays off.
• Several people recount bad experiences in Java/Go/Ruby codebases over-abstracted in the name of DRY, TDD, or design patterns, making debugging and change hard.

Role of comments: “what” vs “why”

• Many agree with the article’s emphasis that comments should primarily explain “why” code is the way it is, not mechanically restate “what” it does.
• However, multiple threads argue “what” comments are still valuable when:
  • The algorithm is subtle or non-obvious (bit hacks, fast inverse square root, tricky loops).
  • Domain rules are opaque (e.g., accounting, banking settlement windows, weird platform bugs).
  • Code uses dense constructs (regexes, complex data pipelines, pointer tricks).
• Some see “what vs why” as a hierarchy (Why→What→How) rather than a hard binary; intermediate layers may need both.

Naming, structure, and alternatives to comments

• A common preference is to keep operations in a readable sequential block and introduce well-named intermediate variables instead of exploding into many tiny methods.
• Views differ on variable length: some like long, descriptive names; others warn overly long identifiers can obscure the operators and logic.
• There’s support for decomposing magic constants into named components to encode the reasoning behind values.

Comment quality, rot, and tooling

• One camp says even mediocre comments are usually better than none, and over-documentation is rare.
• Another stresses that inaccurate “what” comments are harmful, causing mistrust and confusion; they advocate first fixing naming/abstractions/tests before adding such comments.
• Tests and commit messages are proposed as “living documentation” for behavior and rules, though they too can drift.
• LLMs enter the discussion: some now comment with LLMs in mind (“enough context for the model to continue correctly”), while others complain about LLM-generated redundant comments.

General consensus

• No one-size-fits-all rule: use comments to add missing, hard-to-derive context—especially intent, constraints, domain rules, and non-obvious tradeoffs.
• Dogmatic bans on “what” comments or rigid adherence to any book or linter rule are viewed as counterproductive; judgment and empathy for future maintainers matter most.