知识卡片
文档注释写契约
内容
公有API注释应描述契约、参数、返回值和异常，而不是复述实现步骤。实现细节变化快，过时注释会污染信任。发散：注释最值得解释代码无法表达的规则和背景。
参考来源
- 位置：《你真的会写代码吗-2021》第7章《让代码说话：可读性》"7.3.1 注释"（源文件：_epub-src/OEBPS/Text/0017.xhtml）
- 结论依据：原文区分文档注释与实现注释，明确"现代编程趋势是鼓励编写文档注释，但控制编写实现注释"，理由是"API优先于实现，通常比实现更稳定"，而实现方法体"经常变化……程序员经常忘记更新注释"，导致过时注释污染信任。
- 原始内容：现代编程趋势是鼓励编写文档注释，但控制编写实现注释。这样做的原因是：API优先于实现，通常比实现更稳定……相反，方法体经常变化……因为它们经常变化，所以同样需要频繁地更新其中的注释，但是程序员经常忘记更新注释……如果有消息传出，某个代码库中的一些注释可能已过时了、并不可靠，那么所有的注释马上就会变成纯粹的无用信息。