ln-610-code-comments-auditor

Code comment auditing evaluates inline comments and docstrings against six dimensions: whether comments explain rationale (WHY) rather than obvious behavior (WHAT), density targets (15-20%), forbidden content, docstring accuracy, staleness, and legacy cleanup. The audit produces compliance scores per category and actionable findings.

WHY comments explain the reasoning or context behind code decisions; WHAT comments merely restate what the code obviously does. Effective comments focus on WHY—the non-obvious intent, constraints, or trade-offs—making code maintenance faster and reducing cognitive load for reviewers and future maintainers.

Yes. The Skill integrates into code review processes to catch comment quality issues before merge. It also works standalone after major refactors or as a component of broader documentation pipelines, scanning any tech stack and tech-agnostic to language or framework.

Comment density targets 15-20% of source lines. The audit calculates this ratio and flags density outliers—both sparse codebases lacking necessary context and over-commented code that obscures readability—helping teams strike the right balance.

The actuality check identifies comments whose content contradicts current code behavior, flagging them for refresh or removal. This prevents misleading documentation and ensures comments remain a reliable source of truth during maintenance and onboarding.

Yes. The forbidden content check scans comments for policy violations, sensitive data, or inappropriate language, helping teams enforce code review standards and maintain professional documentation across the codebase.