【原】提高软件的可维护性应该包括代码和文档

维护活动，是软件产品交付给用户之后的活动，而交付给用户的软件产品除了程序外还有用户手册等文档，所以，进行软件维护，不仅仅有对程序的危害，还包括对文档的维护。同样，提高软件的可维护性也应该包括代码和文档。

1. 提高程序的可维护性

由于要进行程序维护，就要对代码进行分析，而代码的易读性和易分析性好坏，决定了分析代码的难易程度。所以，提高程序的可维护性，就需要提高代码的易读性和易分析性。提高代码的易读性和易分析性涉及变量/函数命名规则、注释率、嵌套的深度、简单性、分解结构和编码规范等。

提高程序的可维护性有很多技巧，具体可参见《编写可维护软件的十大原则》。

2. 文档的可维护性

维护人员在进行维护活动时，文档是其获得相关信息的重要渠道，这里的文档不仅有用户手册等支持文档，也包括开发文档，特别是维护人员不是开发人员的时候。

维护人员在维护软件之前必须通过阅读相关文档尽可能多地了解需要维护的对象，可以通过文档了解软件的功能、设计、实现和其他与维护相关的问题。

提高软件的可维护性必须提高文档的可维护性。而为了提高文档的可维护性，可以从以下几个方面考虑：

• 文档写作风格：各类文档描述应尽量使用清晰且易理解的文字。例如，尽量使用主动句，减少被动句，而且应当通过多个角度解释复杂的对象。

• 符合文档规范：建立标准化的文档模板，文档中的字体、段落格式和章节编号都应符合标准化要求。

• 做好配置管理：当程序发生变化时应及时进行文档的变更。

具有良好可维护性的文档会具备以下特点：

• 一致性：文档与程序保持一致，不同文档之间也保持一致。

• 可测试性：文档使用定量的方式描述，能够通过测试进行验证。

• 可修改性：文档应该具有连贯和方便使用的结构，包括目录、索引及清晰的相互引用，这样能够保证修改文档比较容易。

• 可跟踪性：文档之间能够相互关联，建立跟踪矩阵，修改一个文档的某个部分应该能够知道所有与之相关或受影响的部分。

这正是：

提高软件维护性，代码首要当其冲

但是代码不唯一，文档也要可维护

参考书目：软件测试设计，作者：马均飞，郑文强，出版社：电子工业出版社