Code Reading -chap8
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+ Chapter8: Documentation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
150. Take advantage of any documentation you find to supplement your code reading effort．(P．241)
利用一切你可以找到的文档去帮助提升你的代码阅读效果。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
151. An hour of code reading Can save you a minute of reading the documentation． (P．241)
一个小时的代码阅读可以节省你一分钟的文档阅读时间。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
152. Use the system specification document to understand the environment where the code
you are reading will operate．(P．242)
使用系统说明文档来理解你所阅读的将会运行的代码所在的环境。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
153. Use the software requirements specification as a benchmark against which to read and
evaluate the code．(P．242)
把软件需求说明看作是一个读取和评估代码的基准。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
154. Use a system’s design specification as a road map to the code structure and as a guide to
specific code elements．(P．242)
把系统的设计说明用作一个关于代码构建的路线图，作为到特定代码元素的一份指南。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
155. The test specification document provides you with data you Can use to dry—run
the code you are reading．(P．242)
测试说明文档提供给你，可以使用来干运行你所阅读的代码的数据 。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
156. when you are dealing with an unknown system，the functional description and the user guide
Can provide you with important background information to better understand the context of
the code you are reading．(p．242)
当你阅读一个不熟悉的系统的时候， 功能说明以及用户指南可以给你提供重要的背景信息，用于更好的理解
你说阅读的代码的上下文
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
157. Use the user reference manual to rapidly obtain background information on presentation and
application logic code components and the
file formats，and error messages you encounter in the code．(P．242)
使用用户索引手册来快速的获取陈述的背景信息，以及应用逻辑代码组件，以及管理员手册来找到接口下的详细信息，
文档格式，以及你在代码中所遇到的错误消息。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
158. Documentation provides you with a shortcut for obtaining an overview of the system or for
understanding the code providing a particular feature．(P．243)
文档给你提供了一个快速获取概览一个系统的捷径，或者提供了理解提供某种特定特性的代码的捷径。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
159. Documentation often mirrors and therefore reveals the underlying system structure．(P．245)
文档常常反映了，同时也因此揭示了底层系统结构。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
160. Documentation helps you understand complicated algorithms and data structures．(p．245)
文档帮助你理解复杂的算法以及数据结构。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
161. A textual description of an algorithm can make the difference between an opaque piece of code
and the chance to understand it．(p．246）
文本化描述一个算法可以使得不透明的代码块以及在理解它的机会两者之间行成差异。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
162. Documentation often elucidates the meaning of source code identifiers．(P．247)
文档常常阐明源代码识别符的含义。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
163. Documentation can provide the rationale behind nonfunctional requirements．(p．247）
文档可以提供在非功能需求后面的，对原理的阐述。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
164. Documentation explains internal programming interfaces．(P．249)
文档解释了内部程序接口。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
165. Because documentation is seldom tested and stressed in the way the actual program code is，
it Can often be erroneous，incomplete，or out of date．(P．249)
由于文档很少被测试以及类似实际程序代码一样进行压力测试，所以文档可能常常是错误的，不完整的或者是过期的。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
166. Documentation provides test cases and examples of actual use．(P．249)
文档提供了测试用例以及实际使用的例子。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
167. Documentation often describes known implementation problems and bugs．(P．251)
文档常常描述已知的实现问题以及故障。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
168. Known environment deficiencies deficiencies are often documented in the source code．(P．252)
已知的环境缺陷常常会在源代码中被文档化。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
169. Change documentation can indicate trouble spots．(P．252)
变更文档可以指出故障点。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－ －－－－－
170. Repetitive or conflicting changes to the same parts of the source code often indicate fundamental
design deficiencies that maintainers try to fix by a series of patches．(P．252)
对源代码相同部分的重复的或者冲突的变更，这常常预示了基础设计的“其维护者试图通过一系列的补丁去修复的” 缺陷，
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
171. Similar fixes applied to different parts of the source code indicate an easily made error oversight
that could conceivably exist in other places as well．(p．253)
相同的修复应用到源代码的不同部分常常预示了容易生成的错误疏忽，该疏忽可以想象的也存在与其它部分。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
172. Documentation may often provide a misleading view of the sourCe code．(p．254)
文档常常提供了一个关于源代码的误导的视图。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
173. Be wary of undocumented features：classify each instance as justiffed，careless or malicious，
and accordingly decide whether the code or the documentation should be fixed．(p．255)
要当心这么几个非文档所有的特性：将各个实例用合乎情理的，粗心大意的，蓄意的方式去分类， 以及
通过是否该代码或者文档应当被修复而去决定对各个实例的分类。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
174. Documentation occasionally does not describe the system as implemented but as it should have
been or will be implemented．(P．255)
文档偶尔不会描述被实现的系统，而是应当被实现的系统或者将要实现的系统。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
175. In source code documentation the word grok typically means“to understand".
源代码文档中，单词grok 典型的意味这”去理解“。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
176. If unknown or idiosyncratically used words hinder the code's understanding，try looking them up in the
documentation”glossary(if it exists)，Th New Hacker's Dictionary[Ray96]，or on a
Web search engine．(p．256)
若未知的或者怪异的单词存在于代码中,并对代码的阅读形成阻碍时， 试着去在”术语（如果存在的话）“中寻找它们，
在《新黑客的字典》中寻找，或者在一个网页搜索引擎中寻找。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
177. When looking for source code documentation，consider nontraditional sources sucn as comments，
standards，publications，test cases，mailing lists，newsgroups， revislon logs，issue—tracking
databases，marketing material，and tlle source code ltself．(P．256)
当寻找源代码文档的时候， 寻求非传统的资源，类如注释，标准， 出版物， 测试用例， 邮件列表， 新闻组，
版本日志，议题追踪数据库， 市场材料， 以及源代码本身。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
178. You should always view documentation wim a critical mind；since documentation is never
executed and rarely tested or formally reviewed to the extent code is．it can often be misleading
or outright wrong．（p．256)
你在阅读源代码的时候必须保持批判性；这是因为文档从来没有被执行过，以及文档很少被测试以及
正式评估过扩展代码， 文档可能常常被误导或者完全错误。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
179. You Can treat flawed code as the specification of the corresponding intended implementation．(P．259)
你可以把有缺陷的代码作为相应的扩展实现之说明来看待。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
180. When reading documentation for a large system，familiarize yourseIf with the documentation’s
overall structure and conventions．(p．264)
当阅读一个大型系统的文档时， 让你自己熟悉整个文档的结构以及约定。
－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
181. When confronted with voluminous documentation，you can improve your readlng productivity by
employing tools or by typesetting the text on a high quality output device such as a laser printer．(P．264)
当遭遇到多倦的长篇的文档时， 你可以通过应用工具或者通过“对文本排字成一个高质量输出设备，例如激光镭射机”
来发展自己的阅读生产率。
++++++++++++++++++++++++++end of chap8 ++++++++++++++++++++++++++++++++++
