知识卡片
外部接口的约定可就地阐明
当库函数或受限接口不便改名时,局部注释可以解释参数顺序、返回值符号或特殊条件,减少读者来回查找。解释应准确指向当前调用并与对应版本相符;若能通过合适包装或名称清楚表达,也可减少重复说明。注释翻译仍可能出错,不能因为它看起来容易读就免查契约。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 第4章 注释
原书出处 · 1 处
- 第4章 注释 4.3.4 阐释 · 查看原书依据
参数或返回值是某个标准库的一部分
参考来源
- 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元003;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。
- 结论依据:原文明确在不能修改的库接口处允许阐释,并警告解释自身有误,支持按控制范围选择说明手段。未在本机运行示例或改变环境。
- 原始内容:尽量让参数或返回值自身就足够清楚;但如果参数或返回值是某个标准库的一部分,或是你不能修改的代码,帮助阐释其含义的代码就会有用。 public void testCompareTo() throws Exception { WikiPagePa