Back to Details

ln-610-code-comments-auditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Comments Auditor

代码注释审计工具

Audit code comments and docstrings quality. Universal for any tech stack.
审计代码注释和文档字符串的质量。适用于任何技术栈。

Purpose

用途

  • Verify comments explain WHY, not obvious WHAT
  • Check comment density (15-20% ratio)
  • Detect forbidden content (dates, author names, historical notes)
  • Validate docstrings match function signatures
  • Ensure comments match current code state
  • Identify legacy comments and commented-out code
  • 验证注释解释的是WHY（原因），而非显而易见的WHAT（内容）
  • 检查注释密度（15-20%的比例）
  • 检测禁用内容（日期、作者姓名、历史记录）
  • 验证文档字符串与函数签名匹配
  • 确保注释与当前代码状态一致
  • 识别遗留注释和被注释掉的代码

Invocation

调用方式

  • Direct: User invokes for code comment quality review
  • Pipeline: Called by ln-100-documents-pipeline (Phase 5, if auditComments=true)
  • 直接调用： 用户发起代码注释质量审查请求
  • 流水线调用： 由ln-100-documents-pipeline调用（第5阶段，当auditComments=true时）

Workflow

工作流程

  1. Scan: Find all source files (auto-detect tech stack)
  2. Extract: Parse inline comments + docstrings/JSDoc
  3. Audit: Run 6 category checks (see Audit Categories below)
  4. Score: Calculate X/10 per category
  5. Report: Output findings and recommended actions
  1. 扫描： 查找所有源文件（自动检测技术栈）
  2. 提取： 解析行内注释 + 文档字符串/JSDoc
  3. 审计： 执行6个类别的检查（见下方审计类别）
  4. 评分： 计算每个类别的X/10分数
  5. 报告： 输出问题发现和建议操作

Audit Categories

审计类别

#CategoryWhat to Check
1WHY not WHATComments explain rationale, not obvious code behavior; no restating code
2Density (15-20%)Comment-to-code ratio within range; not over/under-commented
3No Forbidden ContentNo dates/authors; no historical notes; no code examples in comments
4Docstrings QualityMatch function signatures; parameters documented; return types accurate
5ActualityComments match code behavior; no stale references; examples runnable
6Legacy CleanupNo TODO without context; no commented-out code; no deprecated notes
序号类别检查内容
1WHY而非WHAT注释解释的是设计原理，而非显而易见的代码行为；不重复代码内容
2密度（15-20%）注释与代码的比例在范围内；注释过多或过少都不行
3无禁用内容无日期/作者信息；无历史记录；注释中无代码示例
4文档字符串质量与函数签名匹配；参数已文档化；返回类型准确
5时效性注释与代码行为一致；无过时引用；示例可运行
6遗留内容清理无无上下文的TODO；无被注释掉的代码；无已弃用说明

Output Format

输出格式

markdown
undefined
markdown
undefined

Code Comments Audit Report - [DATE]

代码注释审计报告 - [日期]

Compliance Score

合规分数

CategoryScoreIssues
WHY not WHATX/10N obvious comments
Density (15-20%)X/10X% actual (target: 15-20%)
No Forbidden ContentX/10N forbidden items
Docstrings QualityX/10N mismatches
ActualityX/10N stale comments
Legacy CleanupX/10N legacy items
OverallX/10
类别分数问题数
WHY而非WHATX/10N条显而易见的注释
密度（15-20%）X/10实际比例X%（目标：15-20%）
无禁用内容X/10N项禁用内容
文档字符串质量X/10N处不匹配
时效性X/10N条过时注释
遗留内容清理X/10N项遗留内容
总体X/10

Critical Findings

关键问题发现

  • [Category] 
    path/file:line
    - Issue description. Action: Fix suggestion.
  • [类别] 
    路径/文件:行号
    - 问题描述。操作建议： 修复建议。

Recommended Actions

推荐操作

PriorityActionLocationCategory
HighRemove author namesrc/X:45Forbidden
MediumUpdate stale docstringlib/Y:120Actuality
undefined
优先级操作位置类别
高移除作者姓名src/X:45禁用内容
中更新过时的文档字符串lib/Y:120时效性
undefined

Scoring Algorithm

评分算法

See 
shared/references/audit_scoring.md
for unified formula and score interpretation.
Severity mapping:
Issue TypeSeverity
Author names, dates in commentsCRITICAL
Commented-out code blocksHIGH
Stale/outdated commentsHIGH
Obvious WHAT commentsMEDIUM
Density deviation >5%MEDIUM
Minor density deviationLOW
统一公式和分数解释请参见
shared/references/audit_scoring.md
。
严重程度映射：
问题类型严重程度
注释中的作者姓名、日期严重
被注释掉的代码块高
过时注释高
显而易见的WHAT注释中
密度偏差>5%中
轻微密度偏差低

Reference Files

参考文件

  • Comment rules and patterns: references/comments_rules.md
  • 注释规则和模式：references/comments_rules.md

Critical Notes

重要说明

  • Fix code, not rules: NEVER modify rules files (*_rules.md, *_standards.md) to make violations pass. Always fix the code instead.
  • Code is truth: When comment contradicts code, flag comment for update
  • WHY > WHAT: Comments explaining obvious behavior should be removed
  • Task IDs OK: Task/Story IDs in comments help with code traceability
  • Universal: Works with any language; detect comment syntax automatically
  • Based on: Claude Code comment-analyzer agent patterns
Version: 3.0.0 Last Updated: 2025-12-23
  • 修复代码，而非规则： 绝不要修改规则文件（_rules.md、_standards.md）来让违规项通过。始终修复代码。
  • 代码即事实： 当注释与代码矛盾时，标记注释需要更新
  • WHY > WHAT： 解释显而易见行为的注释应被移除
  • 任务ID允许： 注释中的任务/需求ID有助于代码可追溯性
  • 通用性： 适用于任何语言；自动检测注释语法
  • 基于： Claude Code comment-analyzer agent模式
版本： 3.0.0 最后更新： 2025-12-23