前言

程序员最痛苦的几件事: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。
这个方法落地时会有多方面的问题，若有兴趣实践不妨参考一下我们的路线免得步子太大扯着蛋。

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

操作系统大作业基于Linux的模拟进程调度算法运用c++语言编程在VMware虚拟机里 centos 亲自写亲自测试代码说明书
发布文章博文管理我的博客退出 Trash Temp 操作系统大作业基于Linux的模拟进程调度算法运用c++语言编程在VMware虚拟机里 centos 亲自写亲自测试代码说明书 @[TO ...
软件详细设计说明书_软件测试的基本理论笔记
一.开发与测试流程理论 ##1.软件开发阶段划分 ###需求分析根据客户的要求,清楚了解客户需求中的产品功能.性能.界面和具体规格等,然后进行分析,确定软件产品所要达到的目标. 需求规格说明书 ## ...
详细设计说明书编写规范
第1章引言 1.1 目的使项目详细设计说明书的编写规范化,从而规范软件管理. 尽可能详细地描述程序的各成份的设计考虑,以利于编制程序. [此处加入编写目的] 1.2 背景说明该软件系统名称,开发 ...
医院管理系统详细设计说明书
详细设计说明书 1.引言 1.1编写目的在完成了针对北京工商大学校医院的前期调查,同时与多位学生进行了全面深入的探讨和分析的基础上,提出了这份概要设计说明书. 此概要设计说明书对北京工商大学校医院管 ...
敢不敢尝试自己写个安全扫描器（java）
敢不敢尝试自己写个安全扫描器(java) 年少轻狂的博主毕设题目选择了"网络扫描器的设计与实现",不料看似简单的题目,却隐藏着一个个巨大的难题.对于菜鸟博主而言,这无疑是一次顶着延 ...
sso 之详细设计说明书（下篇）
http://cailin.iteye.com/blog/143116 转载(海纳百川文章http://www.cnblogs.com/David-weihw/a) 本文是单点登录系统(SSO)详细 ...
单点登录系统（SSO）详细设计说明书（下篇）
单点登录系统(SSO)详细设计说明书(下篇) 收藏 3.3输入输出要求解释各输入输出数据的类型,并逐项对格式.数值范围.精度等作出准确定义.对软件的数据输出及必须标明的控制输出量进行解释并举例,包括 ...
【读书笔记】《写给大忙人看的Java SE 8》——Java8新特性总结
2019独角兽企业重金招聘Python工程师标准>>> 阅读目录接口中的默认方法和静态方法函数式接口和Lambda表达式 Stream API 新的日期和时间 API 杂项改进 ...
如何写一份优秀的Java程序员简历？
hello,大家好! 之前给小伙伴们分享过大厂的面经汇总, 面试题刷的怎么样了? 简历准备好了吗? 今天来讨论一下如何写一份优秀的Java程序员简历也会分享几份优秀的大厂简历模板, 下方公众号回复 ...

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

前言

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

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

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

思路

说服

如何自动化

总结

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

最新文章

热门文章