Ln 610 Code Comments Auditor

What it does

The Ln 610 Code Comments Auditor skill analyzes code to assess and improve the quality of comments and docstrings. It verifies that comments explain why the code is written, not just what it does, and checks for adherence to a comment density ratio (typically 15-20%). The tool also identifies potentially problematic content like dates, author names, or deprecated notes within comments, ensuring code maintainability and readability across various tech stacks.

When to use it

This skill is useful in the following scenarios:

• Reviewing code for quality assurance before merging changes.
• Improving the overall documentation of a codebase.
• Identifying and removing outdated or irrelevant comments.
• Ensuring docstrings accurately reflect function signatures and parameters.
• As part of an automated pipeline (when integrated with ln-100-documents-pipeline with auditComments=true).

Key capabilities

• Comment Quality Assessment: Evaluates whether comments explain the rationale behind code, not just its functionality.
• Density Analysis: Checks comment density against a target range (15-20%, but adjustable based on file type).
• Forbidden Content Detection: Identifies and flags dates, author names, historical notes, or code examples within comments.
• Docstring Validation: Ensures docstrings accurately match function signatures and document parameters/return types.
• Actuality Verification: Confirms that comments reflect the current state of the code and are up-to-date.
• Legacy Comment Identification: Detects TODO items without context, commented-out code, and deprecated notes.

Example prompts

• "Analyze this file for comment quality issues: path/to/my_file.py"
• "Run a code comments audit on the entire project."
• "Check the docstrings in this function: my_module.my_function()"

Tips & gotchas

• The skill automatically detects the tech stack being used, so no specific configuration is usually needed.
• Findings are filtered based on context (e.g., McCabe complexity and file path) which can downgrade severity levels. Review the "Advisory" notes in the report for these downgraded findings.
• For detailed information about context validation rules, refer to shared/references/context_validation.md.