知识卡片
常量注释应解释取值依据
常量背后若有选择依据,注释应说明它依赖什么、是大致合理的界限还是精细调出的结果,以及改变它可能影响什么。读者由此能判断怎样调整,而不只是看到一个数字。自明的常量无需重复解释;示例中的线程数、数量上限和图像质量值不能直接作为其他系统的推荐配置。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 常量注释应解释取值依据
- · 第5章小结
原书出处 · 2 处
- · 查看原书依据
为什么它是这个值的“故事”。例如,你可能会在代码中看到如下常量: 这一行看上去可能不需要注释,但很可能选择用这个值的程序员知道得比这个要多: 现在,读代码的人就有了调整这个值的指南了(比如,设置成1可能就太低了,设置成50又太夸张了)。 或者有时常量的值本身并不重要。达
- · 查看原书依据
常量背后的故事,为什么是这个值。 站在读者的立场上思考: ·预料到代码中哪些部分会让读者说:“啊?”并且给它们加上注释。 ·为普通读者意料之外的行为加上注释。 ·在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的。 ·用注释来总结代码块,使读者不致迷失
参考来源
- 位置:《编写可读代码的艺术》说明常量取值的依据(spine 2798;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2722.html`;来源键`s2798-ch05-005`)。
- 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。
- 原始内容:为什么它是这个值的“故事”。例如,你可能会在代码中看到如下常量: 这一行看上去可能不需要注释,但很可能选择用这个值的程序员知道得比这个要多: 现在,读代码的人就有了调整这个值的指南了(比如,设置成1可能就太低了,设置成50又太夸张了)。 或者有时常量的值本身并不重要。达
- 位置:《编写可读代码的艺术》第5章小结(spine 2804;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2728.html`;来源键`s2804-ch05-005`)。
- 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。
- 原始内容:常量背后的故事,为什么是这个值。 站在读者的立场上思考: ·预料到代码中哪些部分会让读者说:“啊?”并且给它们加上注释。 ·为普通读者意料之外的行为加上注释。 ·在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的。 ·用注释来总结代码块,使读者不致迷失