编写代码文档很痛苦。不写文档会导致更大的痛苦——我们无法理解代码。然而，编写文档后忘记更新会造成最终的痛苦：它会说谎并使我们困惑。我们怎么样一次性解决这三种痛苦：禁止所有注释！如果没有注释，我们怎么知道代码的意图是什么？我们向LLM请教。如果LLM无法解释并承认自己无能？那么，我们会自动失败构建，并责怪代码的作者。因此，我们引入了一个新的质量门槛：代码可解释性评分。只有当这个评分足够高时，构建才会通过。
软件工程中最优秀的头脑长期以来一直梦想着自我记录的代码。在1974年，Brian Kernighan和Phillip James Plauger 说过：“计算机程序的唯一可靠文档是代码本身。”在2004年，Steven McConnell在Code Complete中声称：“代码级文档的主要贡献者不是注释，而是良好的编程风格。”在2008年，Robert Martin在Clean Code中建议：“如果我们的编程语言足够表达，或者我们有足够的才能巧妙地驾驭这些语言来表达我们的意图，我们就不需要很多注释——也许根本不需要。”他们都希望同样的事情：自解释的代码。他们只是缺乏强制执行的工具。
我们到底为什么要写注释？一个有一百行的Java方法可能需要花费几个小时才能理解。一个小小的Javadoc块可以节省这段时间：
评论承诺帮助我们，但以两种明显的方式失败。
首先，它们不清晰。 David Parnas曾经说过，“对作者来说似乎清晰而足够的文档，在六个月或六年后必须维护代码的程序员看来通常就像泥浆一样。作者认为显而易见的东西，读者却觉得神秘。
其次，它们腐败。 作为静态元数据，评论不会随代码自动演进。如果shortest()函数的实现不再是递归的，我们可能会忘记更新Javadoc块。这种疏忽导致幻觉文档，会导致错误、破坏信任和浪费调试时间。1999年，Andrew Hunt和Dave Thomas在The Pragmatic Programmer中警告说，“不可信任的评论比没有评论更糟糕。” 最近的分析显示，过时的评论并不罕见，而是普遍存在的。
现在我们有一个可以解决这两个问题的工具：LLM。
与其手动编写Javadoc块，我们可以让IDE按需生成它。LLM读取一百行代码，理解它，并用一句英文总结其意图。现代模型比大多数人类更擅长完成这项任务。文档始终是最新的，因为它是从当前代码生成的，而不是从几个月前编写的过时评论中提取的。
但我们可以更进一步。我们可以将LLM集成到构建流水线中，并要求它评估每个函数的代码可解释性分数（CIS）。如果模型对解释逻辑的信心不足，这表明代码太聪明或太复杂。编译器可以强制执行一个阈值：如果CIS太低，构建失败。这将把可读性从主观偏好转变为客观、可衡量的质量门槛。
一旦这个门槛存在，手动评论不仅变得不必要，而且有害。它们引入了另一种可能与代码矛盾的真相来源。逻辑结论是：完全禁止它们。这迫使开发人员编写干净、结构化的逻辑，这种逻辑本质上是机器可解释的。
Robert Martin希望有更具表现力的语言。他不知道LLMs。今天，我们不需要更好的语言—我们需要一个能够解释任何语言的LLM。如果LLM无法解释代码，我们将责怪程序员并停止构建。
我们正在考虑将我们的实验性面向对象语言EO设定为这种限制。
Translated by ChatGPT gpt-3.5-turbo/42 on 2026-01-11 at 20:46
