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