知识卡片
注释须提供名称之外的信息
“返回月份的日数”若只把getDayOfMonth重新说一遍,没有解释范围、单位或不变量,就增加了一份会漂移的文本。自动要求每个字段或构造器有同款说明,容易产生这种噪声,复制时还可能把version贴到info上。应检查注释是否补充读者需要而代码未表达的信息,不能仅按注释数量判断文档充分。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 4 处
- 第4章 注释 4.4.2 多余的注释 · 查看原书依据
并不能比代码本身提供更多的信息
- 第4章 注释 4.4.6 废话注释 · 查看原书依据
private String info;
- 第5章 格式 5.2.3 垂直方向上的靠近 · 查看原书依据
注释是如何割断两个实体变量间的联系
- 第17章 味道与启发 第17章 味道与启发 · 查看原书依据
注释应该谈及代码自身没提到的东西
参考来源
- 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元005;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。
- 结论依据:原文ContainerBase、默认构造与日期getter、addCD模板及复制错注释共同展示纯复述的成本,支持按信息增量而非覆盖表面判断。未在本机运行示例或改变环境。
- 原始内容:"); } } 这段注释起了什么作用?它并不能比代码本身提供更多的信息。它没有证明代码的意义,也没有给出代码的意图或逻辑。读它并不比读代码更容易。事实上,它不如代码精确,误导读者接受不精确的信息,而不是正确地理解代码。它就像个自来熟的二手车