Back to Details

ln-613-code-comments-auditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Paths: File paths (
shared/
, 
references/
, 
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到SKILL.md所在目录，然后向上一级即为仓库根目录。

Code Comments Auditor (L3 Worker)

代码注释审计器（L3 Worker）

Specialized worker auditing code comments and docstrings quality.
专注于审计代码注释与文档字符串质量的Worker。

Purpose & Scope

目标与范围

  • Worker in ln-610 coordinator pipeline - invoked by ln-610-docs-auditor
  • Audit code comments for quality and compliance across 6 categories
  • Universal for any tech stack (auto-detect comment syntax)
  • Return structured findings to coordinator with severity, location, recommendations
  • Calculate compliance score (X/10) for Code Comments category
  • ln-610协调器流水线中的Worker - 由ln-610-docs-auditor调用
  • 从6个维度审计代码注释的质量与合规性
  • 支持任意技术栈（自动检测注释语法）
  • 向协调器返回结构化检查结果，包含严重程度、位置和改进建议
  • 计算代码注释维度的合规得分（X/10）

Inputs (from Coordinator)

输入参数（来自协调器）

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
.
Receives 
contextStore
with: 
tech_stack
, 
project_root
, 
output_dir
.
必读： 加载
shared/references/audit_worker_core_contract.md
文件。
接收包含以下字段的
contextStore
：
tech_stack
、
project_root
、
output_dir
。

Workflow

工作流程

  1. Parse Context: Extract tech stack, project root, output_dir from contextStore
  2. Scan: Find all source files (use 
    tech_stack
    for detection)
  3. Extract: Parse inline comments + docstrings/JSDoc
  4. Audit: Run 6 category checks (see Audit Categories below)
  5. Collect Findings: Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
  6. Calculate Score: Count violations by severity, calculate compliance score (X/10)
  7. Write Report: Build full markdown report per 
    shared/templates/audit_worker_report_template.md
    , write to 
    {output_dir}/613-code-comments.md
    in single Write call
  8. Return Summary: Return minimal summary to coordinator (see Output Format)
  1. 解析上下文： 从contextStore中提取技术栈、项目根目录、输出目录
  2. 扫描文件： 查找所有源文件（利用
    tech_stack
    进行检测）
  3. 提取内容： 解析行内注释 + 文档字符串/JSDoc
  4. 执行审计： 完成6个维度的检查（详见下方审计维度）
  5. 收集结果： 记录每一项违规内容，包含严重程度、位置（文件:行号）、修复工作量预估（S/M/L）、改进建议
  6. 计算得分： 按严重程度统计违规项数量，计算合规得分（X/10）
  7. 生成报告： 按照
    shared/templates/audit_worker_report_template.md
    模板生成完整Markdown报告，通过单次写入操作保存到
    {output_dir}/613-code-comments.md
  8. 返回摘要： 向协调器返回极简版结果摘要（详见输出格式）

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
序号维度检查内容
1说明原因而非内容注释需解释设计思路，而非重复代码的明显行为；不得复述代码逻辑
2注释密度（15-20%）注释与代码占比需在范围内；避免注释过多或过少
3无禁用内容不得包含日期/作者信息；不得包含历史记录；注释中不得有代码示例
4文档字符串质量与函数签名匹配；参数已文档化；返回类型描述准确
5时效性注释与代码行为一致；无过时引用；示例代码可正常运行
6遗留内容清理无缺失上下文的TODO标记；无被注释掉的代码；无已废弃的说明

Scoring Algorithm

评分算法

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
and 
shared/references/audit_scoring.md
.
必读： 加载
shared/references/audit_worker_core_contract.md
和
shared/references/audit_scoring.md
文件。

Output Format

输出格式

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
and 
shared/templates/audit_worker_report_template.md
.
Write report to 
{output_dir}/613-code-comments.md
with 
category: "Code Comments"
and checks: why_not_what, density, forbidden_content, docstrings_quality, actuality, legacy_cleanup.
Return summary to coordinator:
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/613-code-comments.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
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_worker_core_contract.md
和
shared/templates/audit_worker_report_template.md
文件。
将报告写入
{output_dir}/613-code-comments.md
，标记
category: "Code Comments"
，检查项包括：why_not_what、density、forbidden_content、docstrings_quality、actuality、legacy_cleanup。
向协调器返回如下格式的摘要：
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/613-code-comments.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
严重程度映射：
违规类型严重程度
注释中包含作者姓名、日期CRITICAL（严重）
被注释掉的代码块HIGH（高）
过时注释HIGH（高）
重复代码内容的注释MEDIUM（中）
注释密度偏差超过5%MEDIUM（中）
注释密度小幅偏差LOW（低）

Critical Rules

核心规则

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
.
  • Do not auto-fix: Report violations only; coordinator aggregates for user
  • Fix code, not rules: NEVER modify rules files (*_rules.md, *_standards.md) to make violations pass
  • Code is truth: When comment contradicts code, flag comment for update
  • WHY > WHAT: Comments explaining obvious behavior should be removed
  • Universal: Works with any language; detect comment syntax automatically
  • Location precision: Always include 
    file:line
    for programmatic navigation
必读： 加载
shared/references/audit_worker_core_contract.md
文件。
  • 禁止自动修复： 仅报告违规内容；由协调器汇总后提交给用户处理
  • 修改代码而非规则： 绝不修改规则文件（_rules.md、_standards.md）来使违规项通过检查
  • 代码为基准： 当注释与代码行为矛盾时，标记注释需更新
  • 原因优先于内容： 解释明显代码行为的注释应被移除
  • 通用性： 支持任意编程语言；自动检测注释语法
  • 位置精准： 必须包含
    file:line
    格式的位置信息，以支持程序化导航

Definition of Done

完成标准

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
.
  • contextStore parsed successfully (including output_dir)
  • All source files scanned (tech stack from contextStore)
  • All 6 categories audited
  • Findings collected with severity, location, effort, recommendation
  • Score calculated using penalty algorithm
  • Report written to 
    {output_dir}/613-code-comments.md
    (atomic single Write call)
  • Summary returned to coordinator
必读： 加载
shared/references/audit_worker_core_contract.md
文件。
  • 成功解析contextStore（包括output_dir）
  • 已扫描所有源文件（基于contextStore中的技术栈）
  • 已完成全部6个维度的审计
  • 已收集所有包含严重程度、位置、工作量、建议的检查结果
  • 已通过惩罚算法计算得分
  • 已将报告写入
    {output_dir}/613-code-comments.md
    （原子化单次写入操作）
  • 已向协调器返回结果摘要

Reference Files

参考文件

  • Comment rules and patterns: references/comments_rules.md
Version: 4.0.0 Last Updated: 2026-03-01
  • 注释规则与模式：references/comments_rules.md
版本： 4.0.0 最后更新： 2026-03-01