知识卡片

普通读书笔记卡 · 1915.b

注释补齐上下文

理解等级:未标注

注释应补齐读者理解代码时缺少的信息:设计取舍、边界、已知局限或难以迅速看出的意图。能从代码快速推断的事实通常不必重复;即使信息最终能推出,简明说明若能显著减少推断工作,仍可能有价值。不能机械要求每个函数都有注释,也不能把注释限定为只能解释为什么。

长函数的代码块前可先概括其目的,让读者进入逐行细节前建立方向。做什么、怎么做、为什么都可以写,取决于哪一项能减少理解负担;总结不能替代必要的结构改进。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 3 处

    • · 查看原书依据

      快速推断的事实写注释。 这里“快速”是个重要的区别。考虑一下下面这段Python代码: 从技术上来讲,这里的注释也没有表达出任何“新信息”。如果你阅读代码本身,你最终会明白它到底在做什么。但对于大多数程序员来讲,读有注释的代码比没有注释的代码理解起来要快速得多。 不要为

    • · 查看原书依据

      “做什么”、“怎么做”或者“为什么”的注释(或者同时注释这三个方面)。

    • · 查看原书依据

      帮助读者了解作者在写代码时已经知道的那些事情。本章介绍了如何发现所有的并不那么明显的信息块并且把它们写下来。 什么地方不需要注释: ·能从代码本身中迅速地推断的事实。 ·用来粉饰烂代码(例如蹩脚的函数名)的“拐杖式注释”——应该把代码改好。 你应该记录下来的想法包括:

    参考来源

    - 位置:《编写可读代码的艺术》第5章:选择有理解增量的注释(spine 2794;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2718.html`;来源键`s2794-ch05-001`)。 - 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。 - 原始内容:快速推断的事实写注释。 这里“快速”是个重要的区别。考虑一下下面这段Python代码: 从技术上来讲,这里的注释也没有表达出任何“新信息”。如果你阅读代码本身,你最终会明白它到底在做什么。但对于大多数程序员来讲,读有注释的代码比没有注释的代码理解起来要快速得多。 不要为 - 位置:《编写可读代码的艺术》用总结帮助读者进入低层步骤(spine 2802;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2726.html`;来源键`s2802-ch05-001`)。 - 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。 - 原始内容:“做什么”、“怎么做”或者“为什么”的注释(或者同时注释这三个方面)。 - 位置:《编写可读代码的艺术》第5章小结(spine 2804;来源项目book-sources,`extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part2728.html`;来源键`s2804-ch05-001`)。 - 结论依据:正文与图103..131完整实读;示例的性能数字、参数及实现细节限定于原例,没有执行或推广为当前通用保证。 - 原始内容:帮助读者了解作者在写代码时已经知道的那些事情。本章介绍了如何发现所有的并不那么明显的信息块并且把它们写下来。 什么地方不需要注释: ·能从代码本身中迅速地推断的事实。 ·用来粉饰烂代码(例如蹩脚的函数名)的“拐杖式注释”——应该把代码改好。 你应该记录下来的想法包括: