知识卡片

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

公共文档应补足调用者契约

理解等级:中级

公共API的使用者通常不该先读完整实现才能调用它。说明应帮助理解有意义的输入、结果、失败及约束,提供名称之外真正需要的信息;代码与文档变动时也要同步。短方法不天然免除契约说明,私有方法也可能有复杂不变量;是否写Javadoc应以读者需要为依据,而非要求每个符号填同样模板。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 2 处

    参考来源

    - 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元004;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。 - 结论依据:原文肯定公共API文档又提醒可能失真,后文批评非公共模板,支持按调用需求取舍而不以方法长短作唯一门槛。未在本机运行示例或改变环境。 - 原始内容:没有它们,写Java程序就会变得很难。 如果你在编写公共API,就该为它编写良好的Javadoc。不过要记住本章中的其他建议。就像其他注释一样,Javadoc也可能误导、不适用或者提供错误信息。 4.4 坏注释 大多数注释都属此类。通常,坏注释都是糟糕的代码的支撑或