如何不写一个字完成详细设计说明书(Java体系)

前言

程序员最痛苦的几件事:1.别人不写文档,2.别人不写注释,3.写文档，4.写注释。上一篇博客聊到了这个梗，但要让程序员硬着头皮做一样，相信99%的人会选写注释而不是写文档。毕竟注释还是程序中的一部分，而且不用打开那个倒霉的Word。
今天暂时不讨论为什么开发人员对文档有这么大的抵触情绪，这篇文章主要讨论如何解决最难搞定又往往最没用的软件过程文档——软件详细设计说明书。当然本文讨论的不仅仅是技术问题而且还是管理问题，如果你的直属老板怎么也不同意换模板那这篇文章的方法就不具备可实施性。

为什么说详细设计说明书没用

一般的软件过程文档包括：
需求规格说明书->概要设计->详细设计->确认测试计划->确认测试说明->确认测试报告->总结
从这个序列中可以看处理来详细设计的本身的用意是指导具体的开发工作，但在这个时代我相信除了极少领域的公司或组织外已经不是按照标准的瀑布流程开发了，毕竟蒙着眼睛做出来的东西在大部分时间是没法用的，这时先需求再概设再详设的流程就显得过于笨重，相对于需求规格说明对于需求的跟踪作用，概要设计对于架构的指导作用，详细设计对于代码的指导作用近乎于0。因此详细设计的业务价值几乎为0，但相对应的其动辄几百页的规模实在不是一个一般人能够看完的。就算是看完了也不太可能记得前100页说的是啥。因此这也就是为什么详细设计是开发人员最为头痛也最不愿意面对的文档。

改进详细设计说明书编写的前提

相信大部分传统公司都会有自己的详细设计说明书的模板，这些模板也应该都大同小异。我们要想完成详细设计说明书的自动化，那么需要开发团队能够有权提出对模板的修改，通过将模板调整为能够自动生成的样式。

我们详细设计说明书的改进实践

思路

通过Javadoc以及一系列的工具完成根据代码自动生成说明文档，并将自动生成的文档作为详细设计说明书的主要部分，再将概要设计中关于架构，数据流，接口等核心部分复制出来作为详细说明中的说明部分即完成详细设计说明书的编写。

说服

公司的文档不能说变就变我们要让我们的改进合法合理，我们的路线如下所示：
1.我们首先要先进行公司模板的分析，确定核心内容
2.收集原有模板的详细设计说明书的消耗人力和时间成本数据
3.进行自动化生成实验，计算需要的时间
4.找到相关干系人，直属领导，QA等部分的人，展现数据差异和自动生成的样例，取得认同。
5.通过一个小项目进行实验，验证成熟性和可行性。
6.改进并推广。

如何自动化

1.将通过javadoc自动生成相关文档。我们一般使用IntelliJ Idea来生成，如下图所示。


若遇到字符集问题请在参数中添加-encoding utf-8 -charset utf-8
经过javadoc自动生成一般我们能在输出目录中看到这样的结果

打开index.html会看到类似这样的界面

一般如果只要求电子版文档的到这一步就ok了但如果要求纸质版则还需要下一步。
2.将javadoc转换为其他可以打印的格式
2.1转为chm
通过jd2chm这个工具可以将javadoc生成的html转换为chm文档，我用的0.34这个版本
启动jd2chm，出现下面这个命令行界面

按照提示设置javadoc路径和其他基本配置后既可以生成chm文件里，成功后javadoc文件夹会是这个样子

那个CHM类型的文件就是最后生成的文件，通过打印功能既可以完成chm打印，但这个方法有一个问题就是javadoc必须要使用特定的模板，默认的是不可以的。
2.2 html合并
通过htmlDoc工具将生成的html文件合并为单一doc或pdf，这样就能便于保存和打印了。
1）下载和安装这个工具，url：https://github.com/michaelrsweet/htmldoc/releases
2）打开程序，添加待生成的html

3）配置输出路径

4）点击generate
这个方案的缺点对于中文支持的不好，可能会有乱码
2.3自研转换工具
其实转换过程并不复杂，想要生成中意的格式和模板可以投入一些人力来开发自动转换工具。

总结

本文讨论了如何详细设计的自动化的问题，其实主要还是管理的意识问题，要是boss还是一味的要求按照现有模板编写，那就follow your heart。
这个方法落地时会有多方面的问题，若有兴趣实践不妨参考一下我们的路线免得步子太大扯着蛋。