《代码阅读方法》---笔记（第八章）

第八章：文档

1.常见的开发源代码文档格式

文档两种类型：

1. 二进制文件：他们的生成和阅读都要使用专利产品，如：Microsoft Word或Adobe FrameMaker;
2. 文本文件：其中包含标记语言(markup language)形式的结构和格式化命令。

2.文档种类

1. 系统的规格说明文档(system specification document)：
   详细描述系统的目标、系统的功能需求、管理和技术上的限制、以及成本和日程等要素，了解所阅读代码的运行环境.
2. 软件需求规格说明(software requirements specification)：
   提供对用户需求和系统总体结构的高层描述，并且详细记述系统的功能和非功能性需求，比如数据处理、外部接口、数据库的逻辑模式以及设计上的各种约束。由于软硬件环境和用户需求的不断改变，文档中还可能描述预期的系统演化。是阅读和评估代码的基准.
3. 系统的设计规格说明(system design specification)：
   一般描述系统的构架、数据和代码结构，还有不同模块之间的接口。面向对象的设计会勾画出系统的基本类型以及公开方法。细化的设计规格一般还包括每个模块（或类）的具体信息，比如它执行的处理任务、提供的接口，以及与其他模块或类之间的关系。另外，设计规格说明还会描述系统采用的数据结构，适用的数据库模式等。系统的设计规格说明作为认知代码结构的路线图, 阅读具体代码的指引。
4. 系统测试规格说明(system test specification)：
   包括测试计划、具体的测试过程、以及实际的测试结果。每个测试过程都会详细说明它所针对的模块以及测试用例使用的数据(从中可以得知特定的输入由哪个模块处理)。利用测试规格说明文档为我们提供可以用来预演正在阅读的代码.
5. 用户文档(user documentation)：
   这些文档包括功能描、安装说明、介绍性的引导、参考手册和管理员手册。从用户参考手册中, 我们可以快速地获取, 应用程序在外观与逻辑上的背景知识, 从管理员手册中可以得知代码的接口|文件格式和错误消息的详细信息.

3.文档重要性与作用

1. 在阅读大型系统的文档时，首先要熟悉文档的总体结构和约定。
2. 阅读代码时，应该尽可能地得到任何能够得到的文档。
3. 阅读一小时代码所得到的信息只不过相当于阅读一分钟文档。
4. 使用系统的规格说明文档，了解所阅读代码的运行环境。
5. 软件需求规格说明是阅读和评估代码的基准。
6. 可以将系统的设计规格说明作为认知代码结构的路线图，阅读具体代码的指引。
7. 测试规格说明文档为我们提供可以用来对代码进行预演的数据。
8. 在接触一个未知系统时，功能性的描述和用户指南可以提供重要的背景信息，从而更好地理解阅读的代码所处的上下文。
9. 从用户参考手册中，我们可以快速地获取，应用程序在外观与逻辑上的背景知识，从管理员手册中可以得知代码的接口、文件格式和错误消息的详细信息。
10. 得到文档可以快捷地获取系统的概况，了解提供特定特性的代码。
11. 文档经常能够反映和提示出系统的底层结构。
12. 文档有助于理解复杂的算法和数据结构。
13. 算法的文字描述能够使不透明（晦涩，难以理解）的代码变得可以理解。
14. 文档常常能够阐明源代码中标识符的含义。
15. 文档能够提供非功能性需求背后的理论基础。
16. 文档还会说明内部编程接口。
17. 文档也提供测试用例，以及实际应用的例子。

4.阅读文档需要注意的问题

1. 由于文档很少像实际的程序代码那样进行测试，并受人关注，所以它常常可能存在错误、不完整或过时。
2. 文档常常还会包括书籍的实现问题或bug。
3. 环境中已知的缺点一般都会记录在源代码中。
4. 文档的变更能够标出那些故障点。
5. 对同一段源代码重复或互相冲突的理性，常常表示存在根本性的设计缺陷，从而使得维护人员需要用一系列的修补程序来修复。
6. 相似的修复应用到源代码的不同部分，常常表示一种易犯的错误或疏忽，它们同样可能会在其他地方存在。
7. 文档常常会提供不恰当的信息，误导我们对源代码的理解。
8. 要警惕那些未归档的特性：将每个实例归类为合理、疏忽或有害，相应地决定是否修复代码或文档。
9. 有时，文档在描述系统时，并非按照已完成的实现，而是按照系统应该的样子或将来的实现。

5.正确对待文档的态度

1. 总是要以批判的态度来看待文档，注意非传统的来源，比如注释、标准、出版物、测试用例、列表、新闻组、修订日志、问题跟踪数据库、营销和源代码本身。
2. 总是要以批判的态度来看待文档；由于文档永远不会执行，对文档的测试和正式复查也很少达到对代码的同样水平，所以文档常常会误导读者，或者完全错误。

6.其他

1. 在源代码文档中，单词gork的意思一般是指“理解”。
2. 如果未知的或特殊用法的单词阻碍了对代码的理解，可以试着在文档的术语表（如果丰硕的话）、New Hacker’s Dictionary[Ray96]、或在Web搜 索引擎中查找它们。
3. 对于那些有缺陷的代码，我们可以从中推断出它的真实意图。
4. 在对付体积庞大的文档时，可以使用工具，或将文本输出到高品质输出设备上，比如激光打印机，来提高阅读的效率。

参考：
https://blog.csdn.net/weixin_42561498/article/details/87378105
https://blog.csdn.net/weixin_30778805/article/details/95941141