What is the 'WHY not WHAT' audit category?

It ensures that comments explain the underlying rationale or business logic (the 'Why') rather than simply restating what the code is doing (the 'What').

How does the scoring system work?

Each of the six categories is scored out of 10. A 10/10 indicates no issues, while scores below 4 indicate critical problems like author names in code or broken docstrings.

Which programming languages does the Code Comments Auditor support?

This skill is universal and tech-stack agnostic; it automatically detects the programming language and comment syntax of your source files.

Can this be used in an automated pipeline?

Yes, it is designed to be invoked either directly by a user or as part of the ln-100-documents-pipeline for automated documentation workflows.

Does it automatically fix the comments for me?

The skill provides a detailed report with findings and 'Recommended Actions'. While it identifies what needs to be fixed, it prioritizes code integrity by flagging issues for developer review.

Code Comments Auditor

Name: Code Comments Auditor
Author: levnikolaevich

bylevnikolaevich

•

Herramientas para Desarrolladores

Audits and optimizes code documentation quality to ensure comments explain rationale rather than obvious code behavior.

Acerca de

The Code Comments Auditor is a specialized skill designed to maintain high standards of source code documentation across any programming language. It evaluates comments and docstrings across six critical dimensions: rationale (WHY vs. WHAT), density, forbidden metadata, docstring accuracy, actuality, and legacy cleanup. By providing a structured compliance score and specific remediation actions, it helps developers eliminate redundant comments, remove commented-out code, and ensure that documentation remains a truthful reflection of the codebase. It is particularly effective after major refactorings or as a quality gate within automated documentation pipelines.

Características Principales

Calculates comment-to-code density to maintain the ideal 15-20% ratio
38 GitHub stars
Validates docstring signatures against actual function parameters and return types
Identifies and flags stale comments, legacy notes, and commented-out code blocks
Evaluates 'WHY vs WHAT' to prioritize rationale over redundant logic descriptions
Detects forbidden content such as author names, dates, and historical notes

Casos de Uso

Enforcing coding standards by removing forbidden metadata and author tags from source files
Identifying and cleaning up technical debt such as 'TODO' items without context or dead code blocks
Performing a documentation audit after a major refactoring to ensure comments remain accurate

Acerca de

Características Principales

Calculates comment-to-code density to maintain the ideal 15-20% ratio
38 GitHub stars
Validates docstring signatures against actual function parameters and return types
Identifies and flags stale comments, legacy notes, and commented-out code blocks
Evaluates 'WHY vs WHAT' to prioritize rationale over redundant logic descriptions
Detects forbidden content such as author names, dates, and historical notes

Casos de Uso

Enforcing coding standards by removing forbidden metadata and author tags from source files
Identifying and cleaning up technical debt such as 'TODO' items without context or dead code blocks
Performing a documentation audit after a major refactoring to ensure comments remain accurate