声明：关于代码阅读的研究，很多思想和文字是来自《代码阅读》这本书，再加上自己的学习和工作经验。可以说是类似读书笔记的，我把它作为了毕业论文的第8章，并结合了自己的毕设作品进行解释，毕设源代码github下载地址：https://github.com/chinaran/A-LL1-Compiler。

8.4 项目文档

任何重大的软件开发项目都很有可能伴随产生大量的文档。这些文档有很正式的，也有比较随意的。利用项目中常见的典型文档，可以帮助开发者理解软件代码。

8.4.1 文档类型

系统规格说明文档（System Specification Document）用于详细描述系统的目标、功能性要求、管理和技术上的限制，以及成本和日程范围。系统规格说明文档有助于理解所读代码的运行环境。

软件需求规格说明（Software Requirements Specification）用于提供关于用户需求和整体系统架构的高级描述，详细说明了各种功能性和非功能性需求，比如数据处理、外部接口、逻辑数据库模式，以及设计上的各类约束。（编译系统参见doc下的软件需求说明书.doc文件）

设计规格说明（Design Specification）包含有对系统架构、数据、代码结构以及模块间接口的描述。细化的设计规格说明还会包含每一个模块和类的具体信息，其中还可能会有关于系统使用的数据结构和适用的数据库模式的描述。总之，设计规格说明可以看作是一份代码结构指南，一本有关特定代码的手册。（编译系统参见doc下的数据库设计文档.doc文件）

系统测试规格说明（System’s Test Specification）一般描述测试计划、具体的测试流程和实际的测试结果，还应包含用于测试工作的测试用例。测试规格文档可以提供一些数据用来推演相关代码。（编译系统参见doc下的软件测试报告.doc文件）

用户文档（User Documentation）是由许多不同的文档汇集在一起的，包括功能性描述、安装说明、入门指南、参考手册和管理手册。

8.4.2 阅读文档的作用

● 文档可以帮助你很快了解一个系统的大体情况，理解提供特定功能的程序代码。

● 文档会提供系统的规格说明，可据此对代码进行审查。

● 文档经常能够反映并进而揭示一些底层结构。

● 文档可以帮助理解较为复杂的算法和数据结构。

● 文档通常会对源代码标识符的含义进行解释。

● 文档可以提供非功能性需求背后的理论支撑。

● 文档中还常常可以反映设计者的一些思考：系统需求、架构和实现上的目标、目的以及意图；一些被否决的备选方案及其否决原因。

● 文档通常也会描述实现中的一些已知的问题和bug。

8.4.3 文档中存在的问题

在阅读文档时候要注意，文档有时会提供不正确的信息，误导我们对源代码的理解。一是未记录的特性，有时候一些特性没有被记录在文档中纯粹是由于疏忽所致，特别是那些在产品开发后期才加进来的特性。二是理想化的表达，文档有时对系统描述时，并不是按照系统已经实现出来的样子，而是按照系统应该表现或将要表现出来的样子。总之，开发者始终应以批判的思维来阅读文档。因为文档从来不会执行，同时也很少被测试或正式复查。