知识卡片
注释说明意图
内容
注释不应重复代码做了什么，而应说明意图、约束、边界和不显然的原因。能用代码清楚表达的地方就改代码。发散：好注释像路标，指出背景和危险；坏注释像字幕，复述眼前画面。
参考来源
- 位置：第6章《敏捷编码》"26 用代码沟通"（源文件：_epub-src/OEBPS/text00000.html）
- 结论依据：原文明确"解释代码做了什么的注释用处不那么大。相反，注释要说明为什么会这样写代码"，并批评`//Constructor`这类复述代码的注释是噪音，建议注释说明目的、前置条件、后置条件、异常等代码本身无法表达的信息，直接支持卡片结论。
- 原始内容："如果必须通读一个方法的代码才能了解它做了什么，那么开发人员先要投入大量的时间和精力才能使用它。……在代码可以传递意图的地方不要使用注释。解释代码做了什么的注释用处不那么大。相反，注释要说明为什么会这样写代码。……用注释沟通。使用细心选择的、有意义的命名。用注释描述代码意图和约束。注释不能替代优秀的代码。"