转写说明
本文基于已校验的公开原文进行结构化转写与事实梳理,非原文转载。 转写保留可核验的技术事实,并将工程建议与来源观点明确分开。
- 原作者: ENCI
- 原始来源: https://juejin.cn/post/7709386928819241010
- 原文发布时间: Wed, 18 Nov 2026 15:03:57 GMT
核心结论
来源文章的核心判断是:模型读取代码时,语法结构只能说明“代码做了什么”,命名只能补充对象含义;关于“为什么这样写、哪些行为不能改变、边界条件是什么”的信息,主要来自注释和 docstring。高价值注释因此承担接口说明的作用,应优先记录契约、陷阱、不变量和取舍。
文章列举了四类常见问题:把有副作用的函数误当作纯函数;把受顺序或副作用约束的代码“优化”掉;在缺少前置条件时反复猜测;必须通读较长实现才能理解意图。文章认为,这些问题主要来自信息缺失,而不是单纯的编码能力不足。
能力机制
注释与代码的就近关系,使模型在定位函数时更容易同时获得相关背景;相比独立文档,注释也更可能随代码一起更新,并能通过函数名或关键词检索进入上下文。文章以一段注释和长篇实现作对比,说明短注释有助于减少理解代码所需的上下文。
可写的高价值信息包括:
- 契约:参数约束、返回值含义、异常、副作用和幂等性。
- 陷阱:哪些看似可优化的代码不能改,以及改动后的后果。
- 不变量:顺序依赖、状态前置条件和必须成对执行的操作。
- 取舍:为什么采用当前实现,而不是更简单的方案。
文章建议把“删除后是否容易导致模型或新人写错”作为判断标准。显而易见的代码、无责任人的 TODO、情绪化表达和单纯复述代码的内容不应占用注释。
快速开始
来源提供了注释体检脚本 comment_audit.py,用于扫描 Python 文件中的公共长函数缺少契约、复述型注释、无主 TODO 和超长注释块。
确认的命令为:
| |
脚本默认扫描当前目录,也可以传入目录参数:
| |
源码中给出的判定范围是:公共函数正文不少于 5 行且缺少参数说明;TODO 或 FIXME 未标注负责人;注释中的标识符在下一行重复出现且没有意图词;连续注释达到 6 行且没有意图词。脚本命中问题时退出码为 1,没有命中时为 0。文章示例显示,扫描三个文件可报告四类问题,补充契约并整理注释后,扫描结果为零处问题。
适用边界
注释不能替代类型、测试或运行时断言。能够由类型表达的约束,应优先使用类型;顺序依赖和边界条件可以在适当位置加入断言或测试,但注释仍用于解释原因。自动生成的接口文档也不能替代契约注释,因为它们未必能表达副作用和顺序依赖。
体检脚本使用启发式规则识别复述型注释,存在误报和漏报;它更适合作为检查入口,用于提示人工复核,而不是直接判定注释质量。文章还指出,单条注释过长通常意味着需要拆分逻辑或重新组织职责,而非继续扩写解释。
以下属于基于来源事实的工程建议,而非来源对所有项目作出的保证:先运行体检脚本建立问题清单,再选择容易导致误改的公共函数补充契约;修改函数行为时同步更新相关注释,并把行为变化与注释未同步视为评审问题。注释保存在代码仓库中,并不能据此推导出模型推理数据一定不会离开本机。
核验清单
- 检查公共函数是否说明参数、返回值、异常、副作用和幂等性。
- 检查容易被重写为更“高效”实现的代码是否标明副作用、顺序依赖和改动后果。
- 检查状态机、缓存和批量操作附近是否记录前置条件和不变量。
- 检查复杂实现是否解释了为何不采用看似更简单的方案。
- 删除注释进行反证:若模型或新人可能因此写错,应保留或补充;若不会,应删除噪音。
- 运行
python comment_audit.py app,人工复核脚本报告的契约缺失、复述型注释、无主 TODO 和超长注释块。 - 对行为变更同步更新契约注释,并用测试或断言验证能够自动检查的约束。
来源与核验
- 原始文章
- 页面事实以原始来源及其引用的官方资料为准;版本、星标和模型能力会随时间变化。
- AI Stack 不公开抓取到的全文快照,只发布独立转写与来源入口。