知识卡片
注释写意图与例子
注释可用高层意图交代代码目的,再用精心选择的输入输出澄清容易误解的行为。例子应覆盖真正的分歧,如参数代表子串还是字符集合、边界相等时归哪边、是否允许重复、结果是否排序、返回的是索引还是值。过分简单的正常例可能没有区分力;例子补充规则,不能代替完整契约或执行测试。
意图表达也提供交叉检查:实际步骤可能完全符合字面注释,却与预期结果相反。因此应说明有帮助的目的,并用可执行测试验证结果。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 注释写意图与例子
- · 让意图与实现形成交叉检查
- · 第6章小结
原书出处 · 3 处
- · 查看原书依据
精心挑选的输入/输出例子比千言万语还有效。 例如,下面是一个用来移除部分字符串的通用函数: 这条注释不是很精确,因为它不能回答下列问题: ·chars是整个要移除的子串,还是一组无序的字母? ·如果在src的结尾有多个chars会怎样? 然而一个精心挑选的例子就可以回答
- · 查看原书依据
更高的层次解释了这段程序在做什么。这更符合程序员写这段代码时的想法。 有趣的是,这段程序中有一个bug!函数CompareProductByPrice(例子中没有给出)已经把高价的项目排在了前面。这段代码所做的事情与作者的意图相反。 这是第二种注释更好的原因。除了这个b
- · 查看原书依据
精心挑选的输入/输出例子进行说明。 ·声明代码的高层次意图,而非明显的细节。 ·用嵌入的注释(如Function(/*arg=*/……))来解释难以理解的函数参数。 ·用含义丰富的词来使注释简洁。
参考来源
- 位置:《编写可读代码的艺术》挑选能区分解释的输入输出例(spine 2809;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2733.html`;来源键`s2809-ch06-002`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:精心挑选的输入/输出例子比千言万语还有效。 例如,下面是一个用来移除部分字符串的通用函数: 这条注释不是很精确,因为它不能回答下列问题: ·chars是整个要移除的子串,还是一组无序的字母? ·如果在src的结尾有多个chars会怎样? 然而一个精心挑选的例子就可以回答
- 位置:《编写可读代码的艺术》让意图与实现形成交叉检查(spine 2810;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2734.html`;来源键`s2810-ch06-002`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:更高的层次解释了这段程序在做什么。这更符合程序员写这段代码时的想法。 有趣的是,这段程序中有一个bug!函数CompareProductByPrice(例子中没有给出)已经把高价的项目排在了前面。这段代码所做的事情与作者的意图相反。 这是第二种注释更好的原因。除了这个b
- 位置:《编写可读代码的艺术》第6章小结(spine 2813;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2737.html`;来源键`s2813-ch06-002`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:精心挑选的输入/输出例子进行说明。 ·声明代码的高层次意图,而非明显的细节。 ·用嵌入的注释(如Function(/*arg=*/……))来解释难以理解的函数参数。 ·用含义丰富的词来使注释简洁。