【代码阅读的方法与实践】第8章 文档

第8章 文档

阅读代码时，应该尽可能地得到任何能够得到的文档。
阅读一小时代码所得到的信息只不过相当于阅读一分钟文档。
使用系统的规格说明文档，了解所阅读代码的运行环境。
软件需求规格说明是阅读和评估代码的基准。
可以将系统的设计规格说明作为认知代码结构的路线图，阅读具体代码的指引。
测试规格说明文档为我们提供可以用来对代码进行预演的数据。
在接触一个未知系统时，功能性的描述和用户指南可以提供重要的背景信息，从而更好地理解阅读的代码所处的上下文。
从用户参考手册中，我们可以快速地获取，应用程序在外观与逻辑上的背景知识，从管理员手册中可以得知代码的接口、文件格式和错误消息的详细信息。
得到文档可以快捷地获取系统的概况，了解提供特定特性的代码。
文档经常能够反映和提示出系统的底层结构。
文档有助于理解复杂的算法和数据结构。
算法的文字描述能够使不透明（晦涩，难以理解）的代码变得可以理解。
文档常常能够阐明源代码中标识符的含义。
文档能够提供非功能性需求背后的理论基础。
文档还会说明内部编程接口。
由于文档很少像实际的程序代码那样进行测试，并受人关注，所以它常常可能存在错误、不完整或过时。
文档也提供测试用例，以及实际应用的例子。
文档常常还会包括书籍的实现问题或bug。
环境中已知的缺点一般都会记录在源代码中。
文档的变更能够标出那些故障点。
对同一段源代码重复或互相冲突的理性，常常表示存在根本性的设计缺陷，从而使得维护人员需要用一系列的修补程序来修复。
相似的修复应用到源代码的不同部分，常常表示一种易犯的错误或疏忽，它们同样可能会在其他地方存在。
文档常常会提供不恰当的信息，误导我们对源代码的理解。
要警惕那些未归档的特性：将每个实例归类为合理、疏忽或有害，相应地决定是否修复代码或文档。
有时，文档在描述系统时，并非按照已完成的实现，而是按照系统应该的样子或将来的实现。
在源代码文档中，单词gork的意思一般是指“理解”。
如果未知的或特殊用法的单词阻碍了对代码的理解，可以试着在文档的术语表（如果丰硕的话）、New Hacker's Dictionary[Ray96]、或在Web搜索引擎中查找它们。
总是要以批判的态度来看待文档，注意非传统的来源，比如注释、标准、出版物、测试用例、列表、新闻组、修订日志、问题跟踪数据库、营销和源代码本身。
总是要以批判的态度来看待文档；由于文档永远不会执行，对文档的测试和正式复查也很少达到对代码的同样水平，所以文档常常会误导读者，或者完全错误。
对于那些有缺陷的代码，我们可以从中推断出它的真实意图。
在阅读大型系统的文档时，首先要熟悉文档的总体结构和约定。
在对付体积庞大的文档时，可以使用工具，或将文本输出到高品质输出设备上，比如激光打印机，来提高阅读的效率。