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.

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

01Calculates comment-to-code density to maintain the ideal 15-20% ratio

0238 GitHub stars

03Validates docstring signatures against actual function parameters and return types

04Identifies and flags stale comments, legacy notes, and commented-out code blocks

05Evaluates 'WHY vs WHAT' to prioritize rationale over redundant logic descriptions

06Detects forbidden content such as author names, dates, and historical notes

Casos de Uso

01Enforcing coding standards by removing forbidden metadata and author tags from source files

02Identifying and cleaning up technical debt such as 'TODO' items without context or dead code blocks

03Performing a documentation audit after a major refactoring to ensure comments remain accurate

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add levnikolaevich/claude-code-skills ln-610-code-comments-auditor

For use in Claude.ai and ChatGPT

Download Skill