Comments & Documentation Review Lens

When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.

Comments are not recording a design that already exists. They are the medium in which the design is discovered. Code captures mechanism. Comments capture meaning. Even a perfect programming language could not replace them. The information types are distinct.

When to Apply

• Reviewing code with comments (or conspicuously lacking them)
• When writing new interfaces and considering documentation strategy
• When comments feel useless or redundant
• When a module is hard to use despite having documentation

Core Principles

The Guiding Principle

"Comments should describe things that aren't obvious from the code." — John Ousterhout, A Philosophy of Software Design