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

末蓝、 2022-09-11 11:08 75阅读 0赞

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

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

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

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

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

总体结构就是类似于部署图这种。我要接手一个项目，我首先要从整体上把握，了解它有哪几大块，分别做啥用。  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5bem55u05ouz_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center]  
当然，设计文档可以滚动式维护，随着项目的开展，不断调整、完善，保持同步。上面这个图就是项目快验收了，我总结一下画出来的。第一次画部署图，可能画得不对。

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

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

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

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

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

[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5bem55u05ouz_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center]: /images/20220828/5a51a316f7c64235b86a16df693f8072.png