原创 如何阅读别人的代码8【转】

++++++++++++

第八章： 文档

++++++++++++



150.阅读代码时, 应该尽可能地利用任何能够得到的文档.

151.阅读一小时代码所得到的信息只不过相当于阅读一分钟文档.

152.使用系统的规格说明文档, 了解所阅读代码的运行环境.

153.软件需求规格说明是阅读和评估代码的基准.

154.可以将系统的设计规格说明作为认知代码结构的路线图, 阅读具体代码的指引.

155.测试规格说明文档为我们提供可以用来对代码进行预演的数据.

156.在接触一个未知系统时, 功能性的描述和用户指南可以提供重要的背景信息,从而更好地理解阅读的代码所处的上下文.

157.从用户参考手册中, 我们可以快速地获取, 应用程序在外观与逻辑上的背景知识, 从管理员手册中可以得知代码的接口|文件格式和错误消

息的详细信息.

158.利用文档可以快捷地获取系统的概况, 了解提供特定特性的代码.

159.文档经常能够反映和提示出系统的底层结构.

160.文档有助于理解复杂的算法和数据结构.

161.算法的文字描述能够使不透明(晦涩, 难以理解)的代码变得可以理解.

162.文档常常能够阐明源代码中标识符的含义.

163.文档能够提供非功能性需求背后的理论基础.

164.文档还会说明内部编程接口.

165.由于文档很少像实际的程序代码那样进行测试, 并受人关注, 所以它常常可能存在错误|不完整或过时.

166.文档也提供测试用例, 以及实际应用的例子.

167.文档常常还会包括已知的实现问题或bug.

168.环境中已知的缺点一般都会记录在源代码中.

169.文档的变更能够标出那些故障点.

170.对同一段源代码重复或互相冲突的更改, 常常表示存在根本性的设计缺陷, 从而使得维护人员需要用一系列的修补程序来修复.

171.相似的修复应用到源代码的不同部分, 常常表示一种易犯的错误或疏忽, 它们同样可能会在其他地方存在.

172.文档常常会提供不恰当的信息, 误导我们对源代码的理解.

173.要警惕那些未归档的特性: 将每个实例归类为合理|疏忽或有害, 相应地决定是否应该修复代码或文档.

174.有时, 文档在描述系统时, 并非按照已完成的实现, 而是系统应该的样子或将来的实现.

175.在源代码文档中, 单词gork的意思一般是指”理解”.

176.如果未知的或特殊用法的单词阻碍了对代码的理解, 可以试着在文档的术语表(如果存在的话)|New Hacker’s Dictionary[Ray96]|或在

Web搜索引擎中查找它们.

177.总是要以批判的态度来看待文档, 注意非传统的来源, 比如注释|标准|出版物|测试用例|邮件列表|新闻组|修订日志|问题跟踪数据库|营

销材料|源代码本身.

178.总是要以批判的态度来看待文档; 由于文档永远不会执行, 对文档的测试和正式复查也很少达到对代码的同样水平, 所以文档常常会误导

读者, 或者完全错误.

179.对于那些有缺陷的代码, 我们可以从中推断出它的真实意图.

180.在阅读大型系统的文档时, 首先要熟悉文档的总体结构和约定.

181.在对付体积庞大的文档时, 可以使用工具, 或将文本输出到高品质输出设备上, 比如激光打印机, 来提高阅读的效率.