电子技术论坛_中国专业的电子工程师学习交流社区-中电网技术论坛

标题: 怎么学习阅读大型项目的代码（8） [打印本页]

作者: look_w 时间: 2019-2-18 20:08 标题: 怎么学习阅读大型项目的代码（8）

第八章：文档

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

欢迎光临电子技术论坛_中国专业的电子工程师学习交流社区-中电网技术论坛 (http://bbs.eccn.com/)