知识卡片
注释要信息密度高
注释应以尽量少的阅读负担表达足够准确的信息。删去重复句式、使用清楚的结构,可以同时节省空间和提高明确程度;例如直接写出映射的键和值角色,比逐个复述类型更紧凑。信息密度不是一味少字,必要背景、边界和例子不能为了短而省掉。
精简应优先改进句式并补全行为方向。例如把根据是否抓取过给予不同优先级,改成未抓取过的URL优先级更高,字数减少却回答了原句遗漏的问题。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 3 处
- · 查看原书依据
很高的信息/空间率。 本章其余部分将举例说明如何做到这一点。 让注释保持紧凑 下面的例子是一个C++类型定义的注释: 可是为什么解释这个例子要用三行呢?用一行不就可以了吗? 的确有些注释要占用三行那么多的空间,但这个不需要。
- · 查看原书依据
未曾爬到过的URL将得到较高的优先级——前面那条注释没有包含这部分信息。
- · 查看原书依据
更多的信息装入更小的空间里。下面是一些具体的提示: ·当像"it"和"this"这样的代词可能指代多个事物时,避免使用它们。 ·尽量精确地描述函数的行为。 ·在注释中用精心挑选的输入/输出例子进行说明。 ·声明代码的高层次意图,而非明显的细节。 ·用嵌入的注释(如Fun
参考来源
- 位置:《编写可读代码的艺术》第6章:提高注释的信息密度(spine 2805;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2729.html`;来源键`s2805-ch06-001`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:很高的信息/空间率。 本章其余部分将举例说明如何做到这一点。 让注释保持紧凑 下面的例子是一个C++类型定义的注释: 可是为什么解释这个例子要用三行呢?用一行不就可以了吗? 的确有些注释要占用三行那么多的空间,但这个不需要。
- 位置:《编写可读代码的艺术》用直接句式增加信息(spine 2807;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2731.html`;来源键`s2807-ch06-001`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:未曾爬到过的URL将得到较高的优先级——前面那条注释没有包含这部分信息。
- 位置:《编写可读代码的艺术》第6章小结(spine 2813;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2737.html`;来源键`s2813-ch06-001`)。
- 结论依据:本项正文与图132..158完整实读;按图核对参数、边界与返回索引,不把教学片段当完整实现或已执行测试。
- 原始内容:更多的信息装入更小的空间里。下面是一些具体的提示: ·当像"it"和"this"这样的代词可能指代多个事物时,避免使用它们。 ·尽量精确地描述函数的行为。 ·在注释中用精心挑选的输入/输出例子进行说明。 ·声明代码的高层次意图,而非明显的细节。 ·用嵌入的注释(如Fun