代码即文档

敏捷方法的共同点之一是，它们将编程提升到软件开发的核心地位，其重要性远高于软件工程界通常所认为的。其中一部分是将代码归类为软件系统的主要（如果不是唯一）文档。

我几乎立即感到有必要反驳一个常见的误解。这样的原则并不是说代码是唯一的文档。虽然我经常听到人们这样说极限编程，但我从未听过极限编程运动的领导者说过这样的话。通常需要进一步的文档来作为代码的补充。

代码是主要文档来源的基本原理是，它是唯一足够详细和精确的文档，可以扮演这个角色——Jack Reeves 在其著名的文章《什么是软件设计？》("什么是软件设计？") 中雄辩地阐述了这一点。

这个原则带来了一个重要的结果——程序员必须努力确保代码清晰易读。说代码是文档，并不是说特定的代码库就是好的文档。像任何文档一样，代码可以是清晰的，也可以是难以理解的。代码本身并不比任何其他形式的文档更清晰。（其他形式的文档也可能非常不清楚——我见过很多乱七八糟的 UML 图，举个常见的例子。）

当然，大多数代码库似乎都不是很好的文档。但正如认为将代码声明为文档就排除了其他形式的文档是谬论一样，认为代码通常是糟糕的文档就意味着它“必然”是糟糕的文档也是谬论。编写清晰的代码是可能的，事实上，我相信大多数代码库都可以变得更加清晰。

我认为代码通常难以阅读的部分原因是人们没有认真对待它作为文档。如果没有让代码清晰的意愿，那么它就不太可能自己变得清晰。因此，编写清晰代码的第一步是接受代码就是文档，然后努力使其清晰。我认为这可以追溯到大多数程序员开始编程时所学到的东西。我的老师并没有过多强调代码的清晰性，他们似乎并不重视它，当然也没有谈论如何做到这一点。作为一个整体，我们行业需要更加重视代码的清晰性。

下一步是学习如何做到这一点，在这里，让我给你一个畅销技术作家的建议——没有什么比评审更重要的了。我永远不会在没有很多人阅读并给我反馈的情况下出版一本书。同样，对于清晰的代码来说，没有什么比从其他人那里获得关于哪些内容容易理解、哪些内容令人困惑的反馈更重要的了。（是的，结对编程是实现这一点的好方法。）

对于更具体的建议，我建议阅读一些关于编程风格的好书。《代码大全》(Code Complete) 是首选。我自然会推荐《重构》(Refactoring)——毕竟，重构的很大一部分是让代码更清晰。在《重构》之后，《重构与模式》(Refactoring to Patterns) 是一个显而易见的选择。

你总会发现人们在某些观点上存在分歧。请记住，代码库主要由团队拥有（即使你对其中的一部分代码实行个人所有制）。专业的程序员应该准备调整自己的个人风格，以反映团队的需求。因此，即使你喜欢三元运算符，如果你的团队觉得它们难以理解，也不要使用它们。你可以在你的个人项目中使用你自己的风格编程，但你在团队中所做的任何事情都应该遵循团队的需求。

2015年3月25日转载