知识卡片
文档解释职责关系和约束
有用文档解释代码做什么、为何如此、数据如何组织,以及与其他部分如何连接。逐行复述语法或只列函数参数,不能替代这些语境。
图中的“加一”注释只是重复指令,说明计数对象及为何增加才提供新信息。文档生成工具可以承载人写的解释,问题在缺少内容,不是工具必然无用;对作者显然的前提也应为新读者写明。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- 15.7 与时俱进 · 查看原书依据
文档需要描述代码在做什么。它应该阐明数据的结构以及数据是如何被代码操作的。我第一份写代码的工作是在贝尔实验室,当时我还在上高中。我很幸运我的老板告诉了我,每一行代码都应该有注释。当时我不是很机灵,就做了这样的事情: 正如你可能看到的,这些注释完全没有价值。这样
参考来源
- 位置:《计算机系统解密》15.7 与时俱进(来源项目book-sources,源文件:extracted/计算机系统解密/_epub-src/text/part0152.html)
- 结论依据:本项全部正文与图表实际读取,区分作者示例、推导与实现边界;纠错另有明确说明。
- 原始内容:文档需要描述代码在做什么。它应该阐明数据的结构以及数据是如何被代码操作的。我第一份写代码的工作是在贝尔实验室,当时我还在上高中。我很幸运我的老板告诉了我,每一行代码都应该有注释。当时我不是很机灵,就做了这样的事情: 正如你可能看到的,这些注释完全没有价值。这样