Python 代码注释

为什么需要它

在 Python 项目中，注释往往比代码本身更容易腐烂。很多函数一开始有说明，但随着迭代，参数含义、返回值类型和副作用就没人更新。新成员接手时要反复读实现，才能搞清 config_path 是目录还是文件，force 是布尔值还是枚举。更糟的是，有些注释只写了 # TODO，却没有记录触发条件或安全边界。手动补充注释不仅费时，还容易因为风格不统一导致文档难以检索。

核心能力

这个技能把“写注释”拆成可重复的流程。它会先解析 Python 源码，识别函数、类、模块和关键分支，再根据上下文判断哪些信息值得写入文档。常见输出包括：

• 函数式文档字符串：整理 Args、Returns、Raises，让参数含义不再靠猜。
• 类级说明：补充职责、典型用法和必要的初始化约束。
• 行内提示：在复杂判断、正则或外部调用旁标注原因，例如 # 兼容旧配置键。
• 风格对齐：按已有注释风格生成，避免混用中英文或不同分隔符。

使用时可以输入一段代码，也可以指定某个模块。技能会优先保持代码行为不变，只围绕 def、class 和关键语句生成注释。生成后你可以继续追问，让它调整粒度，比如只补 Args，或把过长的段落拆成多行。

适用边界

它适合补充和修复注释，不适合替代开发者对复杂业务逻辑的判断。如果函数名已经误导，或异常处理缺少上下文，技能只能按现有代码推测。生成结果建议人工复核，尤其是涉及并发、事务和外部系统时。不要指望一次生成就能覆盖所有隐藏约束。