知识卡片
注释应记录取舍与局限
把影响实现选择的背景写进注释:在什么数据上比较过哪些方案、为什么容忍某个限制、未来怎样改进。读者就能理解当前实现为何存在,而不是重复尝试或把有意接受的限制当成未知缺陷。比较结论应附适用条件,历史测量不能当所有输入和环境下的性能保证。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 注释应记录取舍与局限
- · 第5章小结
原书出处 · 2 处
- · 查看原书依据
对于这些数据用二叉树比用哈希表快40% //哈希运算的代价比左/右比较大得多 这段注释教会读者一些事情,并且防止他们为无谓的优化而浪费时间。 下面是另一个例子: //作为整体可能会丢掉几个词。这没有问题。要100%解决太难了 如果没有这段注释,读者可能会以为这是个bug
- · 查看原书依据
内在理由(“指导性批注”)。 ·代码中的缺陷,使用像TODO:或者XXX:这样的标记。 ·常量背后的故事,为什么是这个值。 站在读者的立场上思考: ·预料到代码中哪些部分会让读者说:“啊?”并且给它们加上注释。 ·为普通读者意料之外的行为加上注释。 ·在文件/类的级别上
参考来源
- 位置:《编写可读代码的艺术》记录实现背后的思考(spine 2796;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2720.html`;来源键`s2796-ch05-003`)。
- 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。
- 原始内容:对于这些数据用二叉树比用哈希表快40% //哈希运算的代价比左/右比较大得多 这段注释教会读者一些事情,并且防止他们为无谓的优化而浪费时间。 下面是另一个例子: //作为整体可能会丢掉几个词。这没有问题。要100%解决太难了 如果没有这段注释,读者可能会以为这是个bug
- 位置:《编写可读代码的艺术》第5章小结(spine 2804;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2728.html`;来源键`s2804-ch05-003`)。
- 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。
- 原始内容:内在理由(“指导性批注”)。 ·代码中的缺陷,使用像TODO:或者XXX:这样的标记。 ·常量背后的故事,为什么是这个值。 站在读者的立场上思考: ·预料到代码中哪些部分会让读者说:“啊?”并且给它们加上注释。 ·为普通读者意料之外的行为加上注释。 ·在文件/类的级别上