信息系统可维护性的必要文档

信息系统可维护性的必要文档

要保证信息系统可维护性，文档是必要的，其中包括： 1）系统设计说明书 2）源代码说明 3）数据库设计说明书 4）接口设计说明书（如果有） 5）用户手册 6）系统截图

这两年，公司组织结构或人事调整，接到了一些旧系统的维护任务。这些系统之前不是我负责开发的，接手并不容易。就算以前是我自己负责开发的，但时间一长，许多细节早已忘记，如果要修改增加功能，或者重新部署，都很麻烦。这是软件开发的可维护性问题。影响软件开发的可维护性有这么几样： 1）良好的设计 2）先进的开发技术 3）可维护的开发语言 4）扎实的测试 5）文档

单就特别有助于维护的文档而言，结合我自身的体会，我觉得有这么几个：

1、系统设计说明书 但现实情况是，我们开发的时候，很少有写设计说明书。一般来说，为了追求严谨，相关文档模板繁文缛节，啰哩啰嗦，很多废话，掩盖了真正有用的干货，写起来特别繁琐；这还是次要的，主要原因是项目时间都很紧，根本没有条件细想；而且事先详尽设计，一切都想得清清楚楚，一般来说都不可能。人的认识有自然规律，我许多时候是边做边想，自底向上的开发。如果写设计文档，除了修改代码，还要修改设计文档，二者保持同步，这跟代码中的注释是一样的。这要在必要性、迫切性和项目进度之间取得平衡。

我的看法是，设计文档要写，但 1）可以写粗一点 2）挑重点模块写 3）形式不限。不一定要搞成word，每个模块就用一个记事本描述就可以。画在纸上，拍照也行。 4）格式不限 5）总体结构一定要有

总体结构就是类似于部署图这种。我要接手一个项目，我首先要从整体上把握，了解它有哪几大块，分别做啥用。

当然，设计文档可以滚动式维护，随着项目的开展，不断调整、完善，保持同步。上面这个图就是项目快验收了，我总结一下画出来的。第一次画部署图，可能画得不对。

2、代码说明 对应上图，每个系统的代码存放在哪里，需要有个说明。

3、数据库设计说明书 这个肯定要有，不必多言。我做过的项目，数据库设计说明书是肯定要有的。如果修改表结构，也肯定先修改文档。

4、接口设计说明书 如果有的话。现在有swagger，方便多了。

5、用户手册 系统部署、配置和维护手册，也叫管理手册。注意不是使用手册。

6、系统截图 这是新手了解系统的捷径。生产环境在客户处，不一定能随时访问；而开发环境，由于数据、配置等问题，导致系统有些功能无法使用，甚至随着时间变迁，公司根本就没有可供访问的测试系统，更麻烦的是，由于人员流失，也许知道这个系统的人都不多。如果能在系统鼎盛兴旺时期，留下一些截屏，可以大大加强维护人员对系统的直观认识。如果光看代码，就算代码写得再规范，可读性再好，也要花不少时间去理解。更何况，所谓代码标准规范，根本就是没有一个定论，每个人都有自己的习惯喜好。将希望寄托在代码很好理解上，无异于缘木求鱼。

2021.11.11 应该还要加上《需求规格说明书》

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。