当您设计一款软件时，设计时最重要的一点就是可理解性。安全性、性能和正确性都很重要，但它们次优于可理解性。
被误解的软件会产生Bug缺陷
如果软件的实施者和维护者对软件存在误解，那么软件最终就会出现缺陷。主要缺陷。这些缺陷有多种形式。
最明显的就是正确性问题。如果你无法理解一段代码，你就无法读懂它，无法理解它在做什么，应该做什么。在这里，测试不是你的救命稻草，因为
- （1）它们只能覆盖有限的表面区域，
- （2）它们也会遇到同样的问题：如果你不理解软件，你很可能就无法很好地测试它。
这也会与安全和性能要求纠缠在一起。如果你不了解系统，如何保证它的安全性？你不可能通过理解来获得完美的安全性--这是一个过程，不是一蹴而就的。但是，如果你一开始就不了解你的软件，那么任何安全的希望都会破灭。你会错过一些基本要求，带来严重的简单安全问题，而不是组件之间复杂而微妙的交互所带来的问题。
而当你不了解软件时，为提高性能而做出的任何改变都可能从根本上破坏关键功能或安全行为。缓存可能会泄露信息或扰乱业务逻辑。为解决性能问题而改进查询可能会产生重大缺陷，甚至最终导致性能下降1。
因此，如果您不了解代码，那么尝试对代码进行任何改动都是失败的：添加新功能、修复错误、提高安全性。
我们怎样才能让它变得容易理解呢？
所以剩下的问题就是如何让事情变得容易理解。有几种通用方法。您可以使代码本身易于理解，也可以提供支持文档来帮助理解它。两者都是需要的，但都有局限性。
让代码易于理解
这是我们在软件工程中经常做的事情，尽管很容易忽视它。当我这样做时，我会考虑一些关键因素：
- 记住你的观众。该代码的其他维护者合理地期望知道什么？如果某些内容在您的团队或行业中不是常识，那么您可能应该添加一些注释来解释它。
- 隔离最高复杂性。如果某些东西很复杂，那么值得将其提取到自己的单元（模块，函数，等等）中，以便您可以定义其接口并以更流畅的可读方式使用它，同时也限制了那些试图使用它的人的复杂性。稍后再了解。
- 用新的眼光来阅读它。评估自己的代码的可读性是很困难的。一个技巧是将代码存放几天，然后在一两天后将其全部从工作记忆中移出后，再次阅读它。这将帮助您了解可能会困扰新读者的事情。
- 集成任何代码审查评论。如果有人问代码审查中的某些内容是如何工作的，不要只是在评论中向他们解释。这意味着您的读者不清楚谁拥有您的拉取请求的所有上下文，因此缺乏该上下文的未来读者也不清楚。相反，更新代码以使其更加清晰（结构上或带有注释），然后回复询问他们更改是否有帮助。
添加支持文档
有时，代码会很难理解。这通常发生在需求之间存在紧张关系的时候。例如，性能改进通常会导致代码不太清晰。
从代码本身理解代码库的完整上下文也很困难（不可能？）。尽管我们谈论自记录代码，但代码库并不包含整个系统。
所以我们需要一些支持文档。以下是一些对于理解代码库非常有帮助的内容。
- 系统架构文档。我喜欢为我工作的系统保留系统架构图、关键术语和服务的术语表以及整个系统的解释。这些确实会过时，但过期一个月的文档总比没有好。对于这些，我保留了一个定期的日历任务来更新它，这样它就不会过时。对于成长中的公司来说，入职也是确保其最新的好时机。
- 架构决策记录和设计评审。作为软件工程师，我们在架构和代码设计方面做出了很多决定。当我们做出这些决定时，就是把它们写下来的好时机。这具有三个效果。第一个是明确的：它提供了一个记录，我们可以用它来了解后来做出了什么决定或为什么做出这个决定。第二个不太明显，那就是通过必须写下我们的决定，我们自己会变得更清楚，这迫使我们尝试向其他人解释它。这使得我们更加关注可理解性。第三，这是插入设计审查过程的好地方，或者至少将这些过程广播出来，这样您就可以在编写代码之前在过程的早期阶段获得有关清晰度的反馈。
- 产品需求文件。这些对于我们了解我们正在实施的内容及其重要性非常有帮助。但它们对于以后理解代码的上下文也非常有帮助。这种奇怪的行为到底是有意为之，还是一个错误？如果您可以看看为什么要实施它以及最初的要求，这将有助于您回答这个问题。
- 代码注释。这些是房间里的大象。它们有助于解释特定代码单元的作用及其存在的原因。这些在任何令人惊讶的情况下都非常有帮助，因此它们应该用于人们会关注和困惑的事情。它们也适合指向相关文档，否则在维护代码时很难发现相关文档来理解代码。
这些只是您可以添加支持文档以帮助理解的几种方法！
(banq注：可理解性是一个有关上下文，凡是有关上下文的，都可能有关多个视角，多种状态，同一个符号在不同上下文中理解不同，因此，可理解性虽然最重要，也是最难，基本属于complex和complicated两种复杂性综合体。属于正确废话，最终沦为教条主义)