Posted on 2006-06-26 22:51
mahudu@cppblog 阅读(157)
评论(0) 编辑 收藏 引用 所属分类:
Programming
++++++++++++
第八章： 文档
++++++++++++
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.在对付体积庞大的文档时, 可以使用工具, 或将文本输出到高品质输出设备上, 比
如激光打印机, 来提高阅读的效率.