知识卡片

普通读书笔记卡 · 6991.r.2.i · 生成模型:未记录

注释须提供名称之外的信息

理解等级:中级

“返回月份的日数”若只把getDayOfMonth重新说一遍,没有解释范围、单位或不变量,就增加了一份会漂移的文本。自动要求每个字段或构造器有同款说明,容易产生这种噪声,复制时还可能把version贴到info上。应检查注释是否补充读者需要而代码未表达的信息,不能仅按注释数量判断文档充分。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 4 处

    参考来源

    - 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元005;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。 - 结论依据:原文ContainerBase、默认构造与日期getter、addCD模板及复制错注释共同展示纯复述的成本,支持按信息增量而非覆盖表面判断。未在本机运行示例或改变环境。 - 原始内容:"); } } 这段注释起了什么作用?它并不能比代码本身提供更多的信息。它没有证明代码的意义,也没有给出代码的意图或逻辑。读它并不比读代码更容易。事实上,它不如代码精确,误导读者接受不精确的信息,而不是正确地理解代码。它就像个自来熟的二手车