Why is a comments-first workflow recommended?

Writing interface comments before code forces you to solidify your abstraction. If the comment is difficult to write, it means the design is likely flawed, allowing you to fix it before writing implementation code.

What is the 'Comment Repeats Code' test?

It is a check to see if a comment provides information that is already obvious from the code itself; if a developer could write the comment just by reading the code, the comment is considered noise and should be removed.

How does this skill help with software design?

It uses documentation as a 'canary in the coal mine.' If an interface is hard to describe in a simple sentence, the skill flags it as a likely design problem or a shallow abstraction.

Does this skill work with cross-module dependencies?

Yes, it provides strategies for documenting dependencies that span multiple modules, helping to capture design context that is often lost in traditional per-file documentation.

Comments & Documentation Review

Name: Comments & Documentation Review
Author: codybrom

bycodybrom

•

Aprendizaje y Documentación

Audits comment quality and enforces documentation-driven design principles to improve code maintainability and abstraction depth.

The Comments & Documentation Review skill transforms how developers approach code documentation by treating comments as a medium for design discovery rather than a post-hoc chore. Based on the principles of 'A Philosophy of Software Design,' it analyzes your codebase to identify redundant 'code-repeating' comments, 'shallow' abstractions flagged by convoluted descriptions, and 'comment rot.' By guiding users through a comments-first workflow, the skill helps surface architectural flaws early in the development process, ensuring that interfaces provide clear mental models and that implementation logic captures the 'why' behind the 'how.'

Características Principales

01Enforces a Comments-First workflow to validate design logic before implementation.

02Audits public interfaces for both intuitive mental models and technical precision.

03Uses the 'Hard-to-Describe' signal to detect leaky abstractions and design flaws.

04Identifies 'Comment Repeats Code' anti-patterns to eliminate noise and improve signal.

053 GitHub stars

06Categorizes comments into Interface, Implementation, Cross-Module, and Data Structure types.

Casos de Uso

01Refactoring a complex module where documentation has become outdated or 'rotted.'

02Onboarding onto a legacy codebase to identify missing design context and cross-module dependencies.

03Reviewing a new API design to ensure it is intuitive and usable without reading the source code.

Características Principales

01Enforces a Comments-First workflow to validate design logic before implementation.

02Audits public interfaces for both intuitive mental models and technical precision.

03Uses the 'Hard-to-Describe' signal to detect leaky abstractions and design flaws.

04Identifies 'Comment Repeats Code' anti-patterns to eliminate noise and improve signal.

053 GitHub stars

06Categorizes comments into Interface, Implementation, Cross-Module, and Data Structure types.

Casos de Uso

01Refactoring a complex module where documentation has become outdated or 'rotted.'

02Onboarding onto a legacy codebase to identify missing design context and cross-module dependencies.

03Reviewing a new API design to ensure it is intuitive and usable without reading the source code.