DevOps：怎么实现源代码注释和系统文档的自动化更新？

【编者按】计算机软件传统定义为：软件是计算机系统中与硬件相依存的另外一部分，软件包括程序、数据及其相关文档的完整集合。然而在时下的开发中，文档的合规性每每被忽视的干干净净。本文由 Todd Waits 撰写，讲述应用程序文档化所遭遇的3个主要挑战，下面一块儿展开。本文系 OneAPM 联合高效运维编译整理。

一般状况下，正式的文档（如源代码文档、系统需求与设计文档，或者各种用户文档）会被开发团队忽视得不折不扣，而 DevOps 中关于流程与文档的理念能够帮助缓解这个问题。软件文档一般分为如下几类：代码、需求、设计、系统与用户文档。文档常常会被忽略的缘由之一在于，若是不能与所依赖的开发工具（如版本控制、问题追踪工具、wiki 及源代码）相匹配，标准文档工具及流程反而会对开发团队形成妨碍，并拖慢开发速度。

本博文探讨了文档化所遇到的3个主要挑战：流程、注释源代码以及系统文档；同时解释了以 DevOps 为基础的文档能够经过怎样的方式使全部利益相关者得以访问通用、可信的信息源，从而查看项目的细节。

问题流程

建立、维护用户文档与系统文档时，操做人员一般会使用笨重的二进制文档（好比 .docx）。通常来讲，在文档协做体系中，还包括一长串来来回回的电邮，或者网络共享的文件，人们使用这些形式相互传送文档的更新版本。此外，专用格式（ .docx 与生成的 PDF）每每会由于跨系统操做而产生不一致，从而在跨团队合做时，经常由于工做环境不一样而产生数据损毁。

将二进制文件存储在版本控制系统中是一种解决办法，但管理多个版本的二进制文件仍旧极具挑战。采用自动化文档，并将它们集成在软件开发生命周期（SDLC）中一样存在许多问题：随着项目的进程，这些文档常常会更新地愈来愈少，或者被彻底废弃。大量文档就是个反面教材（使用不当手段解决问题）；每支团队都应当在丰富与简单之间找到平衡。

文档代码「不分家」

理想状况下，机构应该经过规范的来源对文档进行维护与撰写。在讨论文档时，区分客观信息与主观加工过的材料很是重要。信息指的是数据或者记录的来源，而主观材料则是经过有序地组织信息而产生的可用终端产品，这种信息是能够被读者阅读的，可能包括系统需求文档、设计文档、状态报告等等。

信息能够在不一样的源中维护，好比在问题追踪器、wiki 以及代码储存库中；同时，信息应当存储在实际中人们与数据交互或执行的地方。好比在寻找描述某个具体功能的文档时，该文档应就应该存储在相关功能所在之处：代码旁。

若是功能文档没有与代码存在一块儿，一旦功能有所改变，那么工程师不止须要更新代码，还要寻找代码相关的文档以便更新，文档匮乏会拖慢开发的进度，工程师须要维护、管理并利用好这些信息。

在全部信息存好以后，咱们就能够经过工具来撰写你们可以阅读并理解的文档，来为读者提供信息。这些撰写的材料一旦生成，就再也不更改，以做参考信息；生成文档的流程是获取最新数据的方法。将文档材料做为网页上传是保存这类文档的一个完美手段，由于网页显示的老是最新版本的文档。

源代码

长期以来，注释代码的能力都属于编程高级实践的一部分。在过去十年间，人们为了改进文档体验，为各类语言开发了很多工具。这些工具容许开发者将相关信息归档，协助开发人员理解代码。下面提到的一些工具也容许程序员在本身的文档中将测试以可读的方式添加进去。编译代码时，文档中的测试会自动运行，若是程序员修改了代码，却没有更新文档的话，build 就会失败。持续集成环境的快速反馈能够协助程序员，确保其遵照正确的文档策略。

下面的工具是样板库，能够直接从源代码注释中生成可读的文档材料。

• Ruby: RDoc

• Python: Sphinx

• Java: Javadoc

• Ruby, Java, .NET, Flex: Cucumber

• C++等: Doxygen

一般管理者可能没法清楚应该对工程师要求什么样的文档。笔者就不止一次收到过这样的需求——将每一行代码的功能写在注释里。管理者须要了解：这类文档对程序员来讲任务繁重，很快就能摧毁任何程序员在合理的时间内交付有商业价值内容的能力。

而在 DevOps 中，一切都应该被自动化，并找出可理解与简单化之间的平衡点。保持「新对象应该进行文档描述」这个思想，自动文档化全部新对象，多是帮助程序员在代码中添加注释的好办法。可是，若是没有文档也没什么影响的话（好比引发 build 失败），你会发现一切对象都处在未归档的状况下（或者用占位符信息错误归档），从而致使返工，须要从新整理欠下的一大堆文档。

开发人员可使用上面列出的工具来验证文档是否过时，实践效果良好。若是想在一个生命周期的结尾对该项目进行记录的话，应当在重要环节将工具打开。从项目一开始，在编写文档时着眼于每个最小可用的产品：记录实际状况，而不是得出解决方案的过程。

系统、设计和用户文档

撰写系统、设计与用户文档的工具没有注释源代码的工具种类丰富。不少时候，公司须要从头开发本身的通用流程与基础架构。

在近期的一篇博文中，Red Hat 的高级技术文档撰写者Mikey Ariel倡导使用持续集成与单元测试文档。在该文中，Ariel 将这一过程描述为：可以测试文档是否遵照指南（好比，公司使用的是 backend 仍是 back-end）以及语法（利用接口使用像是Hemingway或After the Deadline之类的工具）。使用单元测试文档的理念能够确保公司各个部门之间文档的标准化。

在 DevOpsDays NYC2015 关于文档的讨论中，来自 Etsy 的 Mike Rembestsy 将他们的流程描述为「对数据中心的网络基础结构进行动态记录」。Etsy 使用 Chef 来更新他们的基础结构，同时 Chef 脚本动态地更新Nagios，监视实例与动态编辑、发布网络图。经过在文档中使用 DevOps 的手段，Etsy 的工程师将更新文档的过程自动化，这样在他们完成工做的时候顺便就完成了这一过程。这些理念与实践在保证文档精准的同时，也反映了系统的当前状态。

将文档看成源代码管理，使得信息版本化，并容许我的有能力维护或将较小的数据来源与各种文档材料自动合并。处理可控数据能够经过有效利用安排，将下降上下文切换所带来的不利影响。切换到 DevOps 文档流程与工做流程时，须要转换思想，考虑什么工具对生成文档最为必要。团队在信息生成时越自动化，或者在促进信息管理时越有效，文档的质量与可用性也就越高。最终，以 DevOps 为基础的文档就可以容许全部利益相关者访问一份通用、可信的信息源，来了解项目详情了。

原文连接：Three Challenges to Documentation for DevOps Teams

本文系 OneAPM 工程师编译整理。想阅读更多技术文章，请访问 OneAPM 官方博客。