python-comments

Python 注释

用途

Python 代码注释的两种操作模式：

1. 编写模式 - 添加缺失的注释、改进现有注释、修正负面类型注释
2. 审查模式 - 对所有注释分类、找出缺漏、生成结构化质量报告

核心原则：注释解释为什么，代码解释是什么。类型提示解释类型。

何时调用

编写模式触发条件：

• 用户请求“添加注释”“为此编写文档”或“改进注释”
• 代码审查指出缺少文档字符串或逻辑不清晰
• 新模块／类／函数缺少文档
• 复杂算法或业务规则需要解释

审查模式触发条件：

• 用户请求“审查注释”“检查注释质量”或“审查文档”
• 发布前文档审查
• 为新团队成员准备入职材料
• 评估遗留代码

不应调用的情况

• 代码计划删除
• 用户想生成 API 参考（改用文档工具）
• 用户想生成类型存根（改用类型提示工具）
• 简单脚本或一次性脚本，注释不会带来价值

Python 的 Antirez 注释分类法

来自 antirez 的《编写系统软件：代码注释》的九种注释类型。完整详情请参阅 references/taxonomy.md。

正面类型（编写这些注释）

Type	Name	Python Form	Purpose
1	Function	Docstring	函数／类／模块的作用
2	Design	Docstring or #	架构依据、API 设计选择
3	Why	Inline #	代码背后不明显的原因
4	Teacher	Inline #	领域知识、算法说明
5	Checklist	Inline #	不得跳过或调整顺序的步骤
6	Guide	# section headers	长模块中的导航提示

负面类型（发现并修正这些注释）

Type	Name	Detection	Fix
7	Trivial	复述代码	删除
8	Debt	TODO、FIXME、HACK	解决问题或创建 issue
9	Backup	注释掉的代码	删除（git 会保留历史）

Python 特定映射

文档字符串与行内注释

• 文档字符串（"""..."""）- 类型 1-2。描述接口（作用、参数、返回值、异常）。遵循 PEP 257。
• 行内注释（#）- 类型 3-6。描述实现（原因、方式、背景）。
• 类型提示 - 减少注释负担。在文档字符串中说明语义，而非类型。

类型提示可减少注释负担

# BAD: Comment duplicates type hint
def process(data: list[dict]) -> bool:
    """Process data.

    Args:
        data: A list of dictionaries  # Redundant - type hint says this
    """

# GOOD: Docstring adds semantic meaning
def process(data: list[dict]) -> bool:
    """Process sensor readings and flag anomalies.

    Args:
        data: Sensor readings keyed by timestamp, each containing
              'value', 'unit', and optional 'calibration_offset'
    """

PEP 257 要点

• 单行文档字符串："""Return the user's full name."""（使用祈使语气，以句号结尾）
• 多行文档字符串：摘要行、空行、详细说明
• 所有公开模块、类、函数和方法都需要文档字符串
• 私有方法：逻辑不明显时添加文档字符串

编写模式工作流

分四个阶段执行。

阶段 1：扫描

1. 阅读要添加注释的整个文件／模块
2. 找出所有现有注释和文档字符串
3. 梳理代码结构：模块、类、函数、复杂代码块
4. 记录已有的类型提示（可减少文档字符串负担）

输出： 现有文档和代码结构清单。

阶段 2：分类缺口

对于每个代码元素，确定缺少什么：

1. 模块级 - 缺少模块文档字符串？缺少章节引导注释？
2. 类级 - 缺少类文档字符串？缺少设计理由？
3. 函数级 - 缺少文档字符串？缺少参数语义说明？复杂逻辑缺少 why 注释？
4. 代码块级 - 复杂算法缺少讲解注释？不明显的条件缺少 why 注释？多步骤流程缺少清单注释？

按影响程度排列缺口优先级：

• 严重 - 公共 API 没有文档字符串，复杂算法没有说明
• 高 - 不明显的业务规则没有 why 注释，多步骤流程没有清单
• 中 - 长模块缺少引导注释，缺少设计理由
• 低 - 私有辅助函数没有文档字符串（如果逻辑显而易见，可跳过）

输出： 按优先级排列的缺口清单，并注明每项需要的注释类型。

阶段 3：编写

按照以下规则添加注释：

1. 选择正确的类型 - 使用阶段 2 分类中采用的分类体系
2. 选择正确的形式 - 类型 1–2 使用文档字符串，类型 3–6 使用行内 #
3. 选择正确的风格 - 遵循项目现有的文档字符串风格；默认使用 Google 风格。参见 references/docstring-styles.md
4. 简洁明了 - 每个词都必须有其价值
5. 处理负面注释 - 删除琐碎注释（类型 7），解决技术债或将其记录为问题（类型 8），删除备份代码（类型 9）

各类型的编写规则：

• 类型 1（函数）：使用祈使语气。说明用途、参数语义（如果已有类型提示，则不说明类型）、返回值、引发的异常和副作用。参见 references/docstring-styles.md
• 类型 2（设计）：说明为何选择此方案而非其他方案。放在模块或类级别，或复杂函数上方
• 类型 3（原因）：在不明显的代码上方写一行注释。从“为什么”的理由入手，而不是描述“做什么”
• 类型 4（讲解）：解释领域概念或算法。适用时链接到外部参考资料
• 类型 5（清单）：为步骤编号。标明顺序有依赖关系的步骤。说明跳过步骤会造成什么问题
• 类型 6（引导）：在长模块中添加章节标题。使用 # --- Section Name --- 或 # region/# endregion

输出： 添加注释后的代码。

阶段 4：验证

1. 不添加琐碎注释 - 每条注释都必须提供代码中没有的信息
2. 不重复类型信息 - 文档字符串不重复类型提示
3. 风格一致 - 所有文档字符串均遵循同一种风格（Google/NumPy/Sphinx）
4. 保留现有注释 - 除非明确属于负面类型，否则不要删除有效的现有注释
5. 代码保持不变 - 仅修改注释和文档字符串，不更改任何逻辑

输出： 通过所有检查的最终注释代码。

审查模式工作流

分四个阶段执行。

阶段 1：收集

1. 从目标代码中提取所有注释和文档字符串
2. 记录位置（文件、行、作用域）
3. 记录形式（文档字符串、行内 #、块级 #）
4. 记录关联的代码元素（模块、类、函数、代码块）

输出： 带位置的注释清单。

阶段 2：分类

为每条注释指定：

• 类型（分类体系中的类型 1–9）
• 质量（良好 / 合格 / 较差）
• 准确性（正确 / 过时 / 有误导性）

各类型的质量标准——详情参见 references/taxonomy.md：

• 类型 1（函数）：是否涵盖用途、参数、返回值和异常？是否使用祈使语气？
• 类型 2（设计）：是否说明理由？是否提及考虑过的替代方案？
• 类型 3（原因）：是否解释了原因，而不只是重述代码？
• 类型 4（讲解）：领域说明是否准确？是否链接到来源？
• 类型 5（清单）：步骤是否编号？是否说明跳过步骤的后果？
• 类型 6（引导）：格式是否一致？是否与实际代码章节对应？
• 类型 7（琐碎）：可删除项
• 类型 8（技术债）：是否有可执行的解决路径？
• 类型 9（备份）：可删除项

输出： 已分类并评估质量的注释清单。

阶段 3：差距分析

识别缺失内容：

1. 公共 API 覆盖率 - 带有文档字符串的公共函数／类／模块所占比例
2. 原因注释覆盖率 - 对复杂逻辑块中不明显的推理过程进行说明
3. 设计文档 - 在模块／类级别记录架构决策
4. 负面类型注释数量 - 琐碎、债务和备份注释的数量

严重级别：

• 严重 - 公共 API 缺少文档字符串、误导性注释
• 高 - 复杂逻辑缺少原因注释、注释过时
• 中 - 缺少设计依据、缺少引导性注释
• 低 - 私有方法缺少文档字符串、轻微的风格不一致

输出： 带有严重级别评级的差距分析。

阶段 4：报告

生成结构化审计报告。

审计报告格式

## Comment Audit Report

### Summary
- **Files analyzed:** N
- **Total comments:** N (docstrings: N, inline: N)
- **Comment density:** N comments per 100 LOC
- **Type distribution:** Type 1: N, Type 2: N, ... Type 9: N
- **Quality score:** N/10

### Critical Gaps
- [ ] {file}:{line} - {element} - Missing {type} comment - {impact}

### Issues Found
#### Negative Comments (fix or remove)
- {file}:{line} - Type {N} ({name}) - "{comment text}" - Action: {delete/resolve/rewrite}

#### Outdated Comments
- {file}:{line} - "{comment text}" - Mismatch: {description}

#### Quality Issues
- {file}:{line} - Type {N} - Issue: {description}

### Coverage Metrics
| Scope | With Docstring | Without | Coverage |
|-------|---------------|---------|----------|
| Modules | N | N | N% |
| Classes | N | N | N% |
| Public functions | N | N | N% |
| Public methods | N | N | N% |

### Recommendations
1. **Priority 1:** {action} - {N elements affected}
2. **Priority 2:** {action} - {N elements affected}
3. **Priority 3:** {action} - {N elements affected}

### Comment Style
- **Detected style:** {Google/NumPy/Sphinx/mixed}
- **Consistency:** {consistent/inconsistent}
- **Recommendation:** {standardize on X style}

完整的报告示例请参阅 references/examples/audit-mode-examples.md。

关键限制

• 绝不添加琐碎注释 - 如果代码写着 x += 1，就不要添加 # increment x
• 绝不添加占位文档字符串 - 在复杂函数上写 """Process data."""，比什么都不写更糟糕
• 绝不重复类型提示 - 如果已有类型提示，应说明语义，而不是类型
• 绝不更改代码逻辑 - 只能修改注释和文档字符串，不做任何功能更改
• 保留现有风格 - 与项目现有的文档字符串风格保持一致
• 保留有效注释 - 只修改／删除属于负面类型（7-9）或明显错误的注释

与同包技能的集成

• python-refactor-method - 重构可能需要更新注释。重构后运行写入模式以更新文档字符串
• pytest-patterns - 测试文档字符串可从类型 1（函数）注释中受益。审计模式可评估测试文档
• python-performance-optimization - 性能关键代码可从类型 4（教学型）注释中受益，用于解释算法选择
• python-packaging - 包级文档（__init__.py 文档字符串）遵循类型 1+2 模式