首先，很高兴听到您同事的代码实际上比您见过的其他代码更清晰。这意味着他可能不会用“自记录”作为懒得注释代码的借口。

自文档代码是不需要自由文本注释的代码，以便知情的读者理解它在做什么。例如，这段代码是自记录的:

print "Hello, World!"

这也是:

factorial n = product [1..n]

这也是:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

现在，“知情读者”这个概念是非常主观和情境化的。如果你或其他人在遵循同事的代码方面遇到了困难，那么他最好重新评估一下他对博学读者的看法。为了调用代码自文档化，必须假定对所使用的语言和库有一定程度的熟悉。

我所见过的关于编写“自文档化代码”的最佳论据是，它避免了自由文本注释与代码编写时不一致的问题。最好的批评是，虽然代码可以描述它自己在做什么以及如何做，但它不能解释为什么某些事情会以某种方式完成。

我曾经和一个家伙一起工作，他打算把金融套件卖给一家大公司。他们坚持让他记录源代码，他写了一个30多页的汇编程序，并说“这是有记录的，看”——然后他翻到第13页，有一条评论“bump counter by one”。 伟大的产品，伟大的实现者，但是……

无论如何，在我看来，上面的重要评论是为了设置上下文。这段代码是自记录的:

> from BeautifulSoup import
> BeautifulSoup, Tag def
> replace_a_href_with_span(soup):
>     links = soup.findAll("a")
>     for link in links:
>         tag = Tag(soup, "span", [("class", "looksLikeLink")])
>         tag.contents = link.contents
>         link.replaceWith(tag)

但是，就我个人而言，需要一个背景来充分理解它。

自文档代码是非常清晰的代码，以至于不需要注释。我举个小例子:

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

注释没什么用，因为代码很清楚。文档是一个很好的实践，但是额外的文档会给代码增加不必要的干扰。你的同事需要知道的是，不是每个人都能阅读别人的代码并了解所有的细节。

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

如果没有注释，最后一个片段将很难破译。你可以想象其他更做作的例子。

如果没有注释，代码就不完全清晰，那么还有改进代码的空间。

我并不是说“不要评论不清楚的代码”。我说的是“让你的代码清晰”。

如果你最终让你的代码在某种程度上不清楚，那么使用注释来弥补。

在顺序:

Self-documenting code is code that clearly expresses its intent to the reader. Not entirely. Comments are always helpful for commentary on why a particular strategy was chosen. However, comments which explain what a section of code is doing are indicative of code that is insufficiently self-documenting and could use some refactoring.. Comments lie and become out of date. Code always tells is more likely to tell the truth. I've never seen a case where the what of code couldn't be made sufficiently clear without comments; however, like I said earlier, it is sometimes necessary/helpful to include commentary on the why.

然而，需要注意的是，真正的自文档化代码需要大量的自我和团队纪律。您必须学会以声明的方式编程，并且必须非常谦虚，避免使用“聪明”的代码，而应该使用那些似乎任何人都可以编写的代码。

以下是我对你的问题的最佳回答。

自文档代码是用类、方法、函数和变量名称清晰编写的代码，这些名称使其意图和函数易于理解。如果做得好，它就是文档。

它可以取代注释和文档完善的代码，但我很少见到它。很多时候，程序员认为他们已经足够好了，但是打倒他们的最好方法是开始问问题。如果他们不得不开始解释太多，那么他们的代码就不够清晰。您不应该阅读代码来了解它的功能。

在某些情况下，这样做会更好。如果代码又小又简单，那么添加文档可能会把事情弄得乱七八糟。

包含算法的代码应该包含注释。大多数时候，即使是最初的程序员也不记得几个月前他们在写一个长函数时到底在想什么。