解释复杂代码的注释有什么问题？

许多人声称“评论应解释“为什么”，而不是“如何””。其他人则说“代码应该是自我记录的”，注释应该很少。罗伯特·C·马丁（Robert C. Martin）声称（用我自己的话改写）经常“评论是写得不好的代码的道歉”。

我的问题如下：

解释复杂的算法或带有描述性注释的冗长而复杂的代码段有什么问题？

这样，无需其他开发人员（包括您自己）逐行阅读整个算法来弄清楚算法的作用，他们只需阅读您用普通英语编写的友好描述性注释即可。

英语是“设计”成易于人类理解的。但是，Java，Ruby或Perl旨在平衡人类可读性和计算机可读性，从而损害了文本的人类可读性。人可以更快地理解英语，而他/她可以理解具有相同含义的代码（只要操作不琐碎）。

因此，在编写了用部分人类可读的编程语言编写的复杂代码之后，为什么不添加友好而易懂的英语的描述性简明注释来解释代码的操作呢？

有人会说“代码不难理解”，“使函数变小”，“使用描述性名称”，“不要编写意大利面条式代码”。

但是我们都知道这还不够。这些仅是准则-重要且有用的准则- 但它们并不能改变某些算法很复杂的事实。因此在逐行阅读它们时很难理解。

用一些关于它的一般操作的注释来解释一个复杂的算法真的很糟糕吗？用注释解释复杂的代码有什么问题？

用外行的话来说：

• 有什么不妥的意见本身。错误的是编写需要这些注释的代码，或者假定只要您以通俗易懂的英语来解释它，就可以编写复杂的代码。
• 更改代码时，注释不会自动更新。这就是为什么注释常常与代码不同步的原因。
• 注释不会使代码更易于测试。
• 道歉还不错。您所做的事情要求道歉（编写不易理解的代码）是不好的。
• 能够编写简单代码来解决复杂问题的程序员比编写复杂代码然后写一个长注释解释其代码功能的程序员更好。

底线：

自我解释是件好事，不需要这样做会更好。

导致代码复杂或混乱的原因有很多。在最常见的原因，最好通过重构代码，使其少混乱，不加入任何形式的意见解决。

但是，在某些情况下，精心选择的评论是最佳选择。

• 如果算法本身很复杂且令人困惑，则不仅是其实现（这种方法在数学期刊上得到了广泛的记载，后来被称为Mbogo的算法），那么您在实现的一开始就发表了评论，请阅读类似于“这是Mbogo的用于重新修饰小部件的算法，最初在这里描述：[论文的URL]。此实现包含Alice和Carol的改进[另一篇论文的URL]。” 不要试图比这更详细。如果有人需要更多细节，他们可能需要阅读整篇论文。

• 如果您采取了一些可以用某种特殊记法表示为一两行的东西，并将其扩展为命令性代码的一大类，那么将这些一两行特殊记法放在函数上方的注释中是一种不错的方法告诉读者应该怎么做。这是一个例外“但如果有什么评论失控与代码同步”的说法，因为专业符号可能是多容易找到比代码中的bug。（如果您用英语写了规范，则是另一种方式。）一个很好的例子在这里：https : //dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.cpp#1057 ...

  /**
   * Scan a unicode-range token.  These match the regular expression
   *
   *     u\+[0-9a-f?]{1,6}(-[0-9a-f]{1,6})?
   *
   * However, some such tokens are "invalid".  There are three valid forms:
   *
   *     u+[0-9a-f]{x}              1 <= x <= 6
   *     u+[0-9a-f]{x}\?{y}         1 <= x+y <= 6
   *     u+[0-9a-f]{x}-[0-9a-f]{y}  1 <= x <= 6, 1 <= y <= 6
  

• 如果代码总体上是简单明了的，但是包含一两个看起来过于复杂，不必要或完全错误的东西，但由于某种原因必须采用这种方式，那么您应在看起来可疑的部分上方放置一个注释，其中请说明原因。这是一个简单的示例，其中唯一需要说明的是常量为什么具有特定值。

  /* s1*s2 <= SIZE_MAX if s1 < K and s2 < K, where K = sqrt(SIZE_MAX+1) */
  const size_t MUL_NO_OVERFLOW = ((size_t)1) << (sizeof(size_t) * 4);
  if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
      nmemb > 0 && SIZE_MAX / nmemb < size)
    abort();
  

那么用注释解释复杂的代码怎么了？

这不是对与错的问题，而是Wikipedia文章中定义的“最佳实践” ：

最佳实践是一种方法或技术，该方法或技术始终如一地显示出优于其他方式所达到的结果，并且被用作基准。

因此，最佳实践是首先尝试改进代码，并在不可能的情况下使用英语。

这不是法律，但是找到需要重构的注释代码比需要注释的重构代码更为常见，最佳实践反映了这一点。

美好的一天，精心制作，结构良好且可读的代码将无法正常工作。否则它将无法正常工作。否则会出现无法使用且需要调整的特殊情况。

到那时，您将需要做一些可以改变事情的事情，这样它才能正常工作。尤其是在存在性能问题的情况下，而且经常在所使用的库，API，Web服务，Gem或操作系统之一运行不正常的情况下，您最终可能会提出不建议的建议必不可少，但反直觉或不明显。

如果您没有任何注释来解释为什么选择这种方法，那么很有可能将来有人（甚至有人可能是您）查看代码，然后看看如何将其“修复”为更易读，更优雅且无意间撤消了您的修复，因为它看起来不像是修复。

如果每个人都总是编写完美的代码，那么很显然，看起来不完美的代码是在现实世界中一些棘手的干预下工作的，但事实并非如此。大多数程序员经常编写令人困惑或有些混乱的代码，因此当我们遇到这种情况时，很自然地倾向于整理它。每当我阅读自己写的旧代码时，我都发誓过去的自己是一个白痴。

因此，我不认为注释是对不良代码的道歉，而只是作为您为什么不做显而易见的事情的解释。拥有后，// The standard approach doesn't work against the 64 bit version of the Frobosticate Library将来的开发人员（包括您将来的自己）可以注意该部分代码，并对该库进行测试。当然，您也可以将注释放入源代码管理的提交中，但是人们只会在出现问题后才查看注释。他们将在更改代码时阅读代码注释。

告诉我们我们应该始终在理论上编写完美代码的人并不总是在现实环境中具有丰富的编程经验的人。有时您需要编写性能达到一定水平的代码，有时需要与不完善的系统进行互操作。这并不意味着您不能以优雅且写得很好的方式执行此操作，但是非显而易见的解决方案需要说明。

当我为业余项目编写代码时，我知道没人会读过，但我仍会注释一些令我感到困惑的部分-例如，任何3D几何都涉及我并不完全熟悉的数学-因为我知道什么时候回来在六个月内，我将完全忘记该怎么做。这不是对错误代码的道歉，而是对个人限制的承认。通过不加注释，我要做的就是在将来为自己创造更多的工作。如果我现在能避免的话，我不希望我的未来自我不必要地重新学习一些东西。那可能有什么价值？

注释的需要与代码的抽象级别成反比。

例如，对于大多数实际目的，汇编语言是不带注释的，难以理解。这是一个小程序的摘录，该程序计算并打印了斐波那契数列的各项：

main:   
; initializes the two numbers and the counter.  Note that this assumes
; that the counter and num1 and num2 areas are contiguous!
;
    mov ax,'00'                     ; initialize to all ASCII zeroes
    mov di,counter                  ; including the counter
    mov cx,digits+cntDigits/2       ; two bytes at a time
    cld                             ; initialize from low to high memory
    rep stosw                       ; write the data
    inc ax                          ; make sure ASCII zero is in al
    mov [num1 + digits - 1],al      ; last digit is one
    mov [num2 + digits - 1],al      ; 
    mov [counter + cntDigits - 1],al

    jmp .bottom         ; done with initialization, so begin

.top
    ; add num1 to num2
    mov di,num1+digits-1
    mov si,num2+digits-1
    mov cx,digits       ; 
    call    AddNumbers  ; num2 += num1
    mov bp,num2         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jz  .done           ;

    ; add num2 to num1
    mov di,num2+digits-1
    mov si,num1+digits-1
    mov cx,digits       ;
    call    AddNumbers  ; num1 += num2
.bottom
    mov bp,num1         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jnz .top            ;
.done
    call    CRLF        ; finish off with CRLF
    mov ax,4c00h        ; terminate
    int 21h             ;

即使有评论，也很复杂。

现代示例：正则表达式通常是非常低的抽象结构（小写字母，数字0、1、2，换行等）。他们可能需要样本形式的评论（IIRC的鲍勃·马丁（Bob Martin）确实承认这一点）。这是一个正则表达式，（我认为）应与HTTP（S）和FTP URL匹配：

^(((ht|f)tp(s?))\://)?(www.|[a-zA-Z].)[a-zA-Z0-9\-\.]+\.(com|edu|gov|m
+il|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(/($|[a-zA-Z0-9\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$

随着语言逐步发展到抽象层次结构，程序员能够使用令人回味的抽象（变量名，函数名，类名，模块名，接口，回调等）来提供内置文档。忽略利用此优势，并在其上使用注释在纸上是很懒惰的，这对维护者是不利的，也是不尊重的。

我想到的是在C数字食谱翻译逐字大多以数字食谱在C ++中，我推断开始为数字食谱（在FORTAN），所有的变量a，aa，b，c，cc，等通过每个版本维护。该算法可能是正确的，但是它们没有利用所提供语言的抽象性。他们让我失望。Dobbs博士的文章样本-快速傅立叶变换：

void four1(double* data, unsigned long nn)
{
    unsigned long n, mmax, m, j, istep, i;
    double wtemp, wr, wpr, wpi, wi, theta;
    double tempr, tempi;

    // reverse-binary reindexing
    n = nn<<1;
    j=1;
    for (i=1; i<n; i+=2) {
        if (j>i) {
            swap(data[j-1], data[i-1]);
            swap(data[j], data[i]);
        }
        m = nn;
        while (m>=2 && j>m) {
            j -= m;
            m >>= 1;
        }
        j += m;
    };

    // here begins the Danielson-Lanczos section
    mmax=2;
    while (n>mmax) {
        istep = mmax<<1;
        theta = -(2*M_PI/mmax);
        wtemp = sin(0.5*theta);
        wpr = -2.0*wtemp*wtemp;
        wpi = sin(theta);
        wr = 1.0;
        wi = 0.0;
        for (m=1; m < mmax; m += 2) {
            for (i=m; i <= n; i += istep) {
                j=i+mmax;
                tempr = wr*data[j-1] - wi*data[j];
                tempi = wr * data[j] + wi*data[j-1];

                data[j-1] = data[i-1] - tempr;
                data[j] = data[i] - tempi;
                data[i-1] += tempr;
                data[i] += tempi;
            }
            wtemp=wr;
            wr += wr*wpr - wi*wpi;
            wi += wi*wpr + wtemp*wpi;
        }
        mmax=istep;
    }
}

作为抽象的特殊情况，每种语言都有用于某些常见任务的惯用语/规范代码片段（在C中删除动态链接列表），无论它们看起来如何，都不应记录在案。程序员应该学习这些习语，因为它们是语言的非正式部分。

因此，要解决的问题是：必须避免使用从低级构建块构建的非惯用代码进行注释。而且这比实际情况要少WAAAAY。

我不认为代码中的注释有什么问题。在我看来，注释在某种程度上是不好的，这是由于某些程序员将事情做得太过分了。这个行业有很多潮流，特别是对于极端观点。在此过程中的某个地方，注释的代码等同于错误的代码，我不确定为什么。

注释确实存在问题-您需要在更新它们所引用的代码时使它们保持更新，这种情况很少发生。Wiki或其他内容是更详尽的代码参考文档。您的代码应可读，无需注释。应该在版本控制或修订说明中描述所做的代码更改。

但是，以上所有方法均不能使注释的使用无效。我们没有生活在理想的世界中，因此，无论出于何种原因上述任何一项都不可行时，我宁愿留下一些评论。

我认为您对他的话读得太多了。您的投诉分为两个不同部分：

解释（1）复杂算法或（2）冗长而费解的带有描述性注释的代码有什么问题？

（1）是不可避免的。我认为马丁不会不同意你的看法。如果您正在编写类似快速反平方根之类的内容，则将需要一些注释，即使这仅仅是“邪恶的浮点位级黑客攻击”。除非使用DFS或二进制搜索之类的简单方法，否则阅读您的代码的人不太可能具有使用该算法的经验，因此，我认为注释中应至少提及其含义。

但是，大多数代码不是（1）。您很少会编写一款软件，除了手动滚动互斥实现，模糊的线性代数运算（缺乏库支持）以及新颖的算法（只有您公司的研究小组知道）之外，什么都不是。大多数代码由库/框架/ API调用，IO，样板和单元测试组成。

这就是马丁在谈论的那种代码。他用本章开头的Kernighan和Plaugher的语录回答了您的问题：

不要注释错误的代码-重写它。

如果您的代码中包含冗长而复杂的部分，则您可能无法保持代码干净。解决此问题的最佳方法不是在文件顶部写一段长段落的注释，以帮助将来的开发人员弄清楚它的位置。最好的解决方案是重写它。

这正是马丁所说的：

注释的正确使用是为了弥补我们无法用代码表达自己的意见。注释始终是失败。我们必须拥有它们，因为我们不能总是想出没有它们的表达方式，但是它们的使用并不是值得庆祝的原因。

这是您的（2）。Martin同意，冗长而复杂的代码确实需要注释-但他将代码的责任归咎于编写该代码的程序员，而不是一个含糊不清的想法，即“我们都知道那还不够”。他认为：

清晰，表达力强，注释少的代码远胜于混乱且复杂，注释很多的代码。与其花费时间来编写解释已造成的混乱的评论，不如将其用于清理混乱。

解释复杂的算法或带有描述性注释的冗长而复杂的代码段有什么问题？

没什么。记录您的工作是一个好习惯。

就是说，您在这里有一个错误的二分法：编写干净的代码与编写记录的代码-两者并不矛盾。

您应该关注的是将复杂的代码简化和抽象为更简单的代码，而不是认为“只要有注释就可以使用复杂的代码”。

理想情况下，您的代码应该简单并记录在案。

这样，无需其他开发人员（包括您自己）逐行阅读整个算法来弄清楚算法的作用，他们只需阅读您用普通英语编写的友好描述性注释即可。

真正。这就是为什么在文档中应解释所有公共API算法的原因。

因此，在编写了用部分人类可读的编程语言编写的复杂代码之后，为什么不添加友好而易懂的英语的描述性简明注释来解释代码的操作呢？

理想情况下，编写一段复杂的代码后，您应该（而不是详尽的清单）：

• 将其视为草稿（即计划对其进行重写）
• 形式化算法入口点/接口/角色/等（分析和优化接口，形式化抽象，文档前提条件，后置条件和副作用以及文档错误情况）。
• 编写测试
• 清理和重构

这些步骤都不是微不足道的操作（即每个步骤都可能需要几个小时），并且执行这些操作的回报不是立即的。因此，这些步骤（几乎）总是被折衷（通过开发人员偷工减料，经理偷工减料，截止日期，市场限制/其他现实情况，缺乏经验等）。

某些算法很复杂。因此在逐行阅读它们时很难理解。

您永远不必依靠阅读实现来弄清楚API的功能。执行此操作时，您将基于实现（而不是接口）来实现客户端代码，这意味着模块耦合已陷入地狱，您可能会在编写的每行新代码中引入未记录的依赖关系。已经增加了技术债务。

用一些关于它的一般操作的注释来解释一个复杂的算法真的很糟糕吗？

不-那很好。但是，仅添加几行注释是不够的。

用注释解释复杂的代码有什么问题？

如果可以避免的话，您不应使用复杂的代码。

为了避免复杂的代码，请对接口进行形式化，在API设计上花费的钱要比在实现上花费的钱多8倍（Stepanov建议与实现相比，至少要花10倍的钱在接口上），然后在开发项目时应了解您正在创建一个项目，而不仅仅是编写一些算法。

一个项目涉及API文档，功能文档，代码/质量度量，项目管理等。这些过程都不是一次性完成的快速步骤（所有过程都需要时间，需要深思熟虑和计划，并且都需要您定期回到它们并用细节进行修改/完善）。

无需其他开发人员（包括您自己）逐行阅读整个算法来弄清楚它的作用，他们只需阅读您用普通英语编写的友好描述性注释即可。

我认为这是对“评论”的轻微滥用。如果程序员想读取某些内容而不是整个算法，那么功能文档就是针对此内容。好的，因此功能文档实际上可能出现在源代码中的注释中（也许是通过doc工具提取的），但是就语法而言，尽管就语法而言，它是注释，但对于您的编译器，您应该将它们视为具有不同目的的独立事物。我认为“评论应少”不一定意味着“文件应少”，甚至“版权声明不多”！

该函数中的注释以及代码供他人阅读。因此，如果您的代码中有几行难以理解，并且无法使其易于理解，那么注释对于读者用作这些行的占位符很有用。当读者试图获得一般要旨时，这可能非常有用，但是存在两个问题：

• 注释不一定是正确的，而代码可以完成它的工作。因此，读者对此表示赞同，这并不理想。
• 读者还不了解代码本身，因此，直到以后再回来阅读它们时，他们仍然没有资格修改或重新使用它。在这种情况下，他们在阅读什么？

有例外，但是大多数读者将需要了解代码本身。应该写评论来帮助而不是取代它，这就是为什么通常建议您评论应说“为什么这么做”的原因。知道接下来几行代码的动机的读者更有机会了解他们的工作和方式。

通常，我们必须做复杂的事情。将它们记录下来以供将来理解当然是正确的。有时，此文档的正确位置是代码，可以在其中使文档与代码保持最新。但是绝对值得考虑单独的文档。这也可以更容易地呈现给其他人，包括图表，彩色图片等。那么评论就是：

// This code implements the algorithm described in requirements document 239.

甚至只是

void doPRD239Algorithm() { ...

当然，人们很高兴能与命名的功能MatchStringKnuthMorrisPratt或encryptAES或partitionBSP。更晦涩的名字值得在评论中解释。您还可以添加书目数据和指向从中实现算法的论文的链接。

如果算法复杂，新颖且不明显，那么即使仅用于公司内部流通，也绝对值得一份文档。如果您担心文档丢失，请将其签入源代码管理。

还有另一类代码，它不是算法而是官僚。您需要为另一个系统设置参数，或与其他人的错误进行互操作：

/* Configure the beam controller and turn on the laser.
The sequence is timing-critical and this code must run with interrupts disabled.
Note that the constant 0xef45ab87 differs from the vendor documentation; the vendor
is wrong in this case.
Some of these operations write the same value multiple times. Do not attempt
to optimise this code by removing seemingly redundant operations.
*/

我忘了，我读它，但有是应该出现在你的代码是什么，应该出现什么样的评论之间的锐利和清晰的线条。

我相信您应该评论自己的意图，而不是算法。即评论你的意思，而不是评论你的意思。

例如：

// The getter.
public <V> V get(final K key, Class<V> type) {
  // Has it run yet?
  Future<Object> f = multitons.get(key);
  if (f == null) {
    // No! Make the task that runs it.
    FutureTask<Object> ft = new FutureTask<Object>(
            new Callable() {

              public Object call() throws Exception {
                // Only do the create when called to do so.
                return key.create();
              }

            });
    // Only put if not there.
    f = multitons.putIfAbsent(key, ft);
    if (f == null) {
      // We replaced null so we successfully put. We were first!
      f = ft;
      // Initiate the task.
      ft.run();
    }
  }
  try {
    /**
     * If code gets here and hangs due to f.status = 0 (FutureTask.NEW)
     * then you are trying to get from your Multiton in your creator.
     *
     * Cannot check for that without unnecessarily complex code.
     *
     * Perhaps could use get with timeout.
     */
    // Cast here to force the right type.
    return (V) f.get();
  } catch (Exception ex) {
    // Hide exceptions without discarding them.
    throw Throwables.asRuntimeException(ex);
  }
}

这里没有尝试说明每个步骤执行的操作，它只说明应该执行的操作。

PS：我找到了我所指的来源- 编码恐怖：代码告诉你如何，评论告诉你为什么

但是我们都知道这还不够。

真？从何时起？

在大多数情况下，设计良好并带有好名字的代码绰绰有余。反对使用注释的论点是众所周知的，并已记录在案（如您所指）。

但这是准则（与其他准则一样）。在极少数情况下（以我的经验，大约每2年一次），如果将其重构为较小的清晰功能（由于性能或内聚需求），情况会变得更糟，然后继续进行下去-进行冗长的评论，以说明事物的实质这样做（以及为什么您违反最佳做法）。

代码的主要目的是命令计算机执行某项操作，因此，好的注释永远不能替代好的代码，因为注释无法执行。

也就是说，源代码中的注释是其他程序员（包括您自己）的一种文档形式。如果注释所涉及的抽象问题超出了代码在每个步骤中所做的工作，那么您做的要好于平均水平。该抽象级别随所使用的工具而异。汇编语言例程附带的注释通常比“ APL”具有较低的“抽象”级别A←0⋄A⊣{2⊤⍵:1+3×⍵⋄⍵÷2}⍣{⍺=A+←1}⎕。我认为这可能值得对要解决的问题进行评论，嗯？

如果该代码是微不足道的，则不需要解释性注释。如果代码不平凡，则解释性注释很可能也是不平凡的。

现在，非平凡的自然语言的麻烦在于，我们中的许多人都不善于阅读或编写它。我相信您的书面交流能力非常出色，但是对书面语言了解较少的人可能会误解您的语言。

如果您尽力编写不会被误解的自然语言，那么您最终会得到诸如法律文件之类的东西（众所周知，这些东西比代码更冗长，更难以理解）。

代码应该是您逻辑的最简洁的描述，关于代码的含义应该没有太多争论，因为您的编译器和平台拥有最终决定权。

就我个人而言，我不会说你永远不要写评论。只有这样，您才应该考虑为什么代码需要注释，以及如何解决该注释。这似乎是这里答案的共同主题。

还没有提到的一点是，有时在某些语言将特定语法用于多种目的的情况下，准确地注释一段代码是有帮助的。例如，假设所有变量均为类型float，请考虑：

f1 = (float)(f2+f3); // Force result to be rounded to single precision
f4 = f1-f2;

显式强制转换为floatto的作用float是强制将结果四舍五入到单精度。因此，可以将注释视为只是说出代码的作用。另一方面，将该代码与：

thing.someFloatProperty = (float)(f2*0.1); // Divide by ten

在这里，强制转换的目的是防止编译器以最有效的方式进行精确计算（f2 / 10）[比乘以0.1f更精确，并且在大多数机器上，比除以10.0f更快速]。

如果没有评论，则正在审查以前的代码的人可能会认为错误地添加了强制类型转换，认为该类型是防止编译器发出嘎嘎声的必要，并且不需要。实际上，强制转换的目的是严格按照语言规范的说明进行操作：强制将计算结果四舍五入为单精度，即使是在四舍五入比将结果保持更高的精度更昂贵的机器上也是如此。鉴于强制转换float可以具有多种不同的含义和目的，使用注释指定在特定情况下要使用的含义可以帮助弄清楚实际含义与意图是一致的。

解释代码作用的注释是一种重复形式。如果您更改代码，然后忘记更新注释，则可能引起混乱。我并不是说不要使用它们，只是明智地使用它们。我赞成Bob叔叔的格言：“仅评论代码不能说的内容”。