注释比代码更重要 -

老顽固

2005年3月18日
第3卷，第2期

注释比代码更重要

充分利用内部文档是提高软件质量和加速实施的最容易被忽视的方法之一。

Jef Raskin，独立顾问

在这篇文章中，我将采取一个看似矛盾的立场。我赞同一些程序员声称使代码能够自我文档化的技术，并鼓励开发能够“自动生成文档”的程序。然而，我也认为这些方法无法提供可靠和可维护代码所需的文档。它们只是一种粗略的辅助手段，甚至只能帮助处理文档的一两个方面——不包括最重要的那些方面。

强制执行卓越的代码文档编制是软件开发管理中尚未解决的前沿问题之一。一些解决方案似乎有效，但它们尚未融入编程文化或编程教育中。很少有编程教师会因为文档不足而降低一个运行良好的程序的评分。

我摒弃了极限编程（XP）的支持者为摆脱“不必要”的文档而采取的激进立场。对于一些程序员来说，要求任何文档都被视为妨碍完成“真正工作”的障碍。Matt Stephens 和 Doug Rosenberg 在《极限编程重构：反对 XP 的案例》（Apress，2003 年）中很好地批评了 XP。

当程序员谈到“自文档化代码”时，他们的意思是您应该使用诸如清晰易懂的变量名之类的技术。与其使用 n 或 count，不如使用可读的、自我解释的名称，例如 numberOfApricotsPickedToDate。这是一种极简主义的文档。尽管如此，它还是有帮助的——应该鼓励使用解释性的名称，无论是变量、模块、对象还是程序。

行内注释是有问题的，通常是无用的

t(i) <= t(i) + 13 /* 将 13 加到 t 的第 i 个元素 */

但它们的真正问题在于其强制的简洁性。当语言语法迫使程序员变得简短时，快速写下注释的冲动就会增强：此类注释被限制在一行的一部分中。当缩进很深时，它确实可能只是一小部分

blix.VK(tofu.haha.cogau) & 00110011B /* 掩码 */

许多注释变得如此简洁，以至于您必须理解代码才能解释注释。随着程序的不断编写或更新，此类注释通常会被进一步截断或完全丢失。因此，它们也是维护方面的难题。

我不使用行内注释，并且我不鼓励与我一起工作的程序员使用它们。如果您要编写注释，请至少给自己完整的一行空间。或者，更好的是，给自己尽可能多的空间。一些开发环境将注释限制为单行。如果您希望进行多行注释，则必须将其表示为一组单行。这意味着没有自动换行——更不用说最简单的笔记软件提供的许多其他功能了。您想更改注释？您将不得不手动调整所有行长。这是惩罚性的，不鼓励文档编制，应该像 GOTOs 一样被淘汰。

任何不允许完全流动且任意长的注释的语言或系统都严重落后于时代。我们使用转义字符来从代码“转义”到注释是落后的。理想情况下，注释应该是默认设置，并提供一种方法来标记偶尔的代码行。

自动文档生成器创建流程图、继承图、目录、索引、主题列表、交叉引用和上下文相关帮助条目。一个生成器宣称自己能够“自动且持续地更新源代码文档的所有方面，以便整个团队拥有触手可及的所有必要信息。 [它]可以使用存储在字典和源文件中的信息自动生成源代码文档。”

显而易见的问题是，它们做得非常糟糕。任何做过良好文档编制的人都知道，即使生成索引也不是一项直接的、自动的任务。不太明显的问题是，许多编码人员认为，一旦他们在代码上运行了文档构建器，他们就记录了代码。这与常见的综合症相同，即一旦拼写检查器不再标记任何单词，就认为文档的拼写是正确的。如果您收到带有程序的此类“文档”，并且发现它远非足够，请记住“耳听为虚，眼见为实”。

但是，代码永远无法自我文档化，自动文档生成器也无法创建所需内容的根本原因是，它们无法解释编写程序的原因，以及选择这种或那种方法的理由。他们无法讨论采取某些替代方法的原因。例如

:注释: 对于感兴趣的数据集，二分查找比 Boyer-Moore 算法慢，因此我们使用了更复杂但更快速的方法，即使这个问题乍一看似乎不适合字符串搜索技术。 :结束注释

此注释不仅命名了所使用的技术，还解释了为什么没有采用更简单的方法。

好的文档应该可以独立阅读，其中展示了如何实现设计（并使其运行，当然）。从好的文档中重建代码比尝试根据代码创建文档要容易得多。事实上，不可能获取代码并创建本应在开发代码时编写的文档。

Donald Knuth 的著作对于所有严肃的程序员来说都是圣经（除了他关于宗教的著作）。他的论文“文学编程”（《计算机杂志》，1984 年 5 月；转载于 Knuth, D. CSLI Lecture Notes 27：《文学编程》，斯坦福，1992 年）是必读之作。我不认为我们需要他的所有机制，但首先编写文档，用自然语言创建方法，并描述其背后的想法的基本概念是高质量商业编程的关键。我强调商业，因为我们都知道客户不满意的巨大成本，以及处理可避免的客户来电的更高成本。使用内部文档是提高软件质量和加速实施的最容易被忽视的方法之一。

我所说的文档类型的一个示例出现在我为 Susan Lammers 的《Programmers at Work: Interviews》（Microsoft Press，1986 年）所做的采访中。标题写着：“此程序演示了 Raskin 如何将可执行代码嵌入到文字处理器生成的文本中。” 这也是使用转义方法而不是注释来编写代码的一个例子。

重要的是不要在这个问题上教条主义。我可以想象一位编程经理阅读了这篇文章和 Knuth 的著作后说“这是我问题的答案！”并强制要求所有工作都以这种方式完成。正如 Frederick Brooks 在《人月神话》（Addison Wesley，1995 年）中告诉我们的那样，“没有银弹。” 一位已经学习了文档优先风格的 competent 程序员有时会想到代码方面的解决方案，先编写代码，然后编写文档，或者会应用混合策略——尤其是在不涉及复杂的算法设计时。只要程序员普遍坚持（并真诚地支持）文档优先的方法，就不应阻止这样做。

不要相信任何声称代码可以自我文档化或自动文档化的程序员、经理或销售人员。事实并非如此。好的文档包含背景信息和决策信息，这些信息无法从代码中推导出来。很难想象任何可预见的软件或机器人可以从参与编程项目的人员那里收集到这些信息——至少它必须理解自然语言，这仍然是 AI 社区的圣杯。

事先、清晰且广泛的文档编制是创建能够生存和适应的软件的关键

要素。按照高标准进行文档编制将缩短开发时间，产生更好的工作成果，并提高

底线。对于任何技术而言，很难要求更多。

任何技术。

喜欢它，讨厌它？请告诉我们

[email protected] 或 www.acmqueue.com/forums

JEF RASKIN，芝加哥大学计算机科学教授，最出名的是他的著作《人性化界面》（Addison-Wesley，2000 年），以及在 Apple 创建 Macintosh 项目。他拥有多项界面专利，为世界各地的公司提供咨询服务，并经常被邀请在会议、研讨会和大学发表演讲。他当前的项目“人性化环境”（http://humane.sourceforge.net/home/index.html）正在计算机科学界和商业界引起关注。

最初发表于 Queue 第 3 卷，第 2 期——
在数字图书馆中评论本文