Conectar

Comments & Documentation Review

codybrombycodybrom
•
3
•
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.