comment-guidelines

To enforce code comment guidelines, apply the WHY over WHAT principle during code edits and reviews. This removes redundant comments that restate implementation details while preserving rationale, design decisions, and explanations for non-obvious behavior.

The best way to remove redundant comments is to enforce a WHY-not-WHAT policy during editing. Automatically strip comments that restate obvious implementation details, keeping only rationale and design decisions to improve readability and maintainability.

To write comments explaining reasoning, focus on the WHY by documenting edge cases, design decisions, and interface intent. Ensure these rationale explanations are retained during edits while removing comments that merely describe what the code does.

Yes, this code comment policy applies across programming languages. It enforces readability and intent guidelines universally during editing and review, ensuring WHY-not-WHAT explanations are retained and redundant comments are removed regardless of the language.

You should not apply the WHY over WHAT principle when a comment explicitly clarifies interface intent, edge cases, or non-obvious behavior. The policy preserves these rationale explanations and only removes comments that restate obvious implementation details.