软件是不断发展的，软件的变化是不可避免的。一般来说，在软件投入使用后，为改变软件所做的任何工作都被认为是维护。维护工作消耗了一个软件项目总生命周期成本的70%以上1。如果你想一想，你会意识到维护工作对于保持软件的生命力是多么的关键。有趣的是，阅读代码的行为是软件开发者进行的所有维护活动中最耗时的部分。
既然可读性对软件的维护具有如此重要的意义，我们就来了解一下如何定义它。在自然语言中，可读性被定义为一个文本的易懂程度。在文学作品中，可读性是由每个词的平均音节、平均句子长度等指标来客观判断的。将一个文本的可读性水平从平庸提高到良好，可以使其交流目标的成功和失败之间产生差异。
源代码不是文档
你会经常看到软件开发者把源代码当作主要的或者有时是唯一的文档。为了在实践中体现这一点，代码必须足够的详细和精确。但是原始形式的源代码是不能作为纯文本阅读的。如前所述，可读性在使软件的可访问性和可维护性方面起着巨大作用。任何写好的文档都必须易于理解，不仅是团队的直接成员，而且是未来的利益相关者。一些例子说明了为什么这一点很重要：
- 当与外部模块对接时，消费者应该理解现有模块所暴露的接口。
- 要扩展一个模块，需要详细了解现有的模型和概念。
- 为了更快地识别一个错误并进行修补，详细的文档可能是关键。
当然，为了使文档有效，它必须和代码本身一起被维护。当重构代码时，必须确保文档也能反映出变化。所有经验丰富的工程团队都会在代码更新时，把动力放在跟踪文档的变化上。
如何写好文档？
在写文档时，有三条黄金法则，即在写注释时问自己这些问题：
- 这段代码是做什么的？
- 它是如何做到的？
- 别人是如何在其他地方使用它的？
当你把注释当作源代码的一部分时，要确保它在合并过程中被审查。如果说这篇文章有什么启示的话，那就是将文档与源代码同等对待，作为审查过程的一部分。
嵌入的文档有助于程序员在上下文中停留并彻底理解。它还表现出与其他常规指标（如软件质量、代码流失率等）的显著关联程度。一个代码库主要由一个团队而不是个人拥有。重要的是，开发人员要付出努力，以确保他们写的代码是清晰和可读的。有些团队可能喜欢跳过代码文档，以节省时间、金钱和精力。但请记住，一旦产品被转移到另一个团队，或在需要更新时，这可能会导致更多的开支。
