直接回答：可以让AI写注释，但目标不应是“提高注释覆盖率”，而是保留代码无法自解释的原因、约束、权衡与风险。注释一旦与代码不一致会直接误导维护者，因此能用更好的命名和结构表达的内容，优先改代码。[1]
注释应该解释“为什么”，而不是翻译代码
如果代码本身已经清楚表达“做什么”，让AI逐行复述只会增加噪声。PEP 8关于注释的指导强调：与代码矛盾的注释比没有注释更糟，更新代码时应同步更新注释。[1]
| 值得注释 | 通常不值得 |
|---|---|
| 业务约束为什么存在 | 把函数名翻译成中文 |
| 外部系统的非显而易见限制 | 重复if/for正在做什么 |
| 算法权衡与复杂度原因 | 显而易见的赋值 |
| 安全/兼容性特殊处理 | “这里调用API” |
| 临时方案的退出条件/Issue | 没有负责人和期限的TODO |
AI写注释的最佳输入
- 代码片段；
- 调用它的业务场景；
- 不可改的兼容/性能/安全约束；
- 相关Issue或设计决策；
- 希望保留的术语。
公共API更需要结构化注释
对SDK、库函数和公共API，注释/文档应清楚说明行为、参数、返回值、错误和边界，不应只写实现细节。Google的API reference comments指南也强调把用户需要理解的API行为写清楚。[2]
一个好用的AI检查法
让AI不是“补注释”，而是先标出：哪些地方代码意图无法从命名和结构看懂。能通过重命名或拆函数解决的，优先改代码；只有无法从代码本身表达的背景才进入注释。
代码评审时再问一句
“如果半年后代码变了，这条注释最容易在哪种情况下变成谎言？”能够显著减少脆弱注释。
参考来源
- Python PEP 8：Comments（核验于 2026-08-08）
- Google Developer Style：API reference comments（核验于 2026-08-08）
更新记录
- 2026-08-08：核验官方资料并完成全文结构化撰写。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
相关文章
百度热点