程序员到架构师，除了代码，还有文档和图

---

前言

作为人类，我们天生就被视觉所吸引。在这个信息爆炸的时代，从精炼的代码到清晰的文档，再到直观的图，我们追求的是更高效、更直观的信息传递方式。

尽管一段优雅的代码能够以其简洁和精确性展现出强大的表达力，但它无法保证，每一次它所传递的信息都是准确无误的。代码的内容虽然可以表达自身，但函数的命名可能会产生误解，变量的命名和代码的结构也未必能始终如一地准确传达其意图。即使我们不断的使用优秀的编程风格和实践，在努力使这种联系更加直接和明确，但这仍然需要开发者的自律和认真的工作。

所以在复杂的开发环境中，我们需要超越代码本身，学会使用文档和图，来提高我们的沟通效率，确保信息的准确传递。

---

一、书面设计文档

文档应该作为代码和口头交流的补充

前文中说过，程序员到架构师，得先学会如何说话。有效的交流方式可以帮助人们更好的理解业务模型，这不仅有助于提高沟通效率，还能确保最终产品更好地满足业务需求。

然而，口头沟通虽然直接，却易随时间消逝，可能导致信息的混淆和误解；而且它的受众范围有限。另一方面，纯粹的代码阅读可能会让读者淹没在复杂细节中，难以捕捉到代码背后的设计意图和行为逻辑。

因此，书面设计文档成为了沟通的基石，它不仅阐明了系统设计的深层次含义，还帮助团队成员聚焦于核心元素，从而清晰地传达设计思路。

文档应该注意鲜活

对于许多程序员来说，提到编写文档可能引发一种抵触情绪：“我的代码已经足够清晰，有问题直接找我，迅速解答，何必多此一举？”他们担忧是文档的字数、格式乃至维护成本。然而，这种认识忽略了文档的真正价值：它不仅仅是文字的堆砌，而是 对模型概念的解释，是在代码细节中指引方向的路标，是帮助理解预期使用风格的工具。

根据团队的具体理念，设计文档可以非常简洁，不必拘泥于正式的格式，只要能够促进有效交流即可。使用团队内部的共通语言可以使文档更加简洁明了，当领域模型准确反映了业务知识时，应用程序的需求就成了模型内部的自然展现，文档也就无需赘述背后的业务逻辑。

重要的是，如果设计文档中的术语未能在后续的讨论和代码中得到体现，那么这份文档就未能发挥其应有的作用。这可能是因为文档内容偏离了主题，或者是因为它未被持续更新，从而失去了相关性。

二、图——架构讨论的直观语言

每当我和我的同事在讨论应用架构设计的会议时，如果不在白板或画板上画图，我就很难讨论下去。因为讨论过程不断涌现的新的概念和词汇会使我的大脑不由自主的偏离原先的方向。

举个经典的例子（懂的都懂）：

简单、非正式的UML图能够维系整个讨论主题。通过绘制一幅包含当前问题最关键的3-5个对象的图，这样每个人都可以集中注意力，所有人关于对象关系会达成一致的认识，更重要的是，大家都会使用相同的对象名称。如此，口头讨论会更加高效。当人们尝试不同的想法时，图也就随之改变，这种视觉辅助使得口头讨论更加高效，草图的灵活性恰好能够捕捉讨论中的动态变化。

UML图擅长描绘对象间的交互和关系。但是UML图无法传达模型的两个最重要的方面，一个方面是模型所表示的概念的意义，另一方面是对象应该做哪些事情。因此，在讨论中，我们需要一边绘制图形，一边用语言来赋予它们更丰富的内涵。

图形是一种强有力的沟通和解释工具，尤其适合促进头脑风暴。简洁的小型图表能够有效地达到这一目的，而那些涵盖整个对象模型的复杂大图往往会失去沟通和解释的效果，因为它们将读者淹没在繁杂的细节之中，缺乏明确的目标。因此，我们应该避免使用过于全面的对象模型图，甚至是那些包含所有细节的UML系统数据图。

---

总结

设计文档是时间的容器，它捕捉并保持了设计的活力，确保每个人都在同一页上。

而图形，像UML这样的工具，将讨论锚定在白板之上，让思路清晰，让交流高效。

作为架构师，我们的挑战在于创造清晰的愿景，并通过代码、文档和图形将其传达给世界。