我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
所谓的自文档代码的真正问题在于它传达了它实际做的事情。虽然一些注释可以帮助别人更好地理解代码(例如，算法步骤等)，但它在一定程度上是多余的，我怀疑你能否说服你的同行。
然而，文档中真正重要的是代码中没有直接体现出来的东西:潜在的意图、假设、影响、限制等等。
能够通过快速浏览来确定代码执行X操作比能够确定代码不执行Y操作要容易得多。他必须记录Y…
你可以给他看一个代码的例子，看起来很好，很明显，但实际上并没有覆盖所有的输入基，比如，看看他是否能找到它。
其他回答
首先，考虑下面的代码片段:
/**
* Sets the value of foobar.
*
* @foobar is the new vaue of foobar.
*/
public void setFoobar(Object foobar) {
this.foobar = foobar;
}
在这个例子中，每3行代码有5行注释。更糟糕的是，注释没有添加任何你在阅读代码时看不到的东西。如果你有10个这样的方法，你可能会得到“注释盲视”，没有注意到一个偏离模式的方法。
当然，更好的版本应该是:
/**
* The serialization of the foobar object is used to synchronize the qux task.
* The default value is unique instance, override if needed.
*/
public void setFoobar(Object foobar) {
this.foobar = foobar;
}
不过，对于简单的代码，我更喜欢没有注释。意图和整体组织最好在代码之外的单独文档中解释。
您可能希望向您的同事指出的一件事是，无论他的代码是如何自我记录的，如果考虑并放弃了其他替代方法，那么该信息将丢失，除非他用该信息注释代码。有时，了解考虑了替代方案以及为什么不选择它同样重要，并且代码注释最有可能随着时间的推移而幸存下来。
如果没有注释，代码就不完全清晰，那么还有改进代码的空间。
我并不是说“不要评论不清楚的代码”。我说的是“让你的代码清晰”。
如果你最终让你的代码在某种程度上不清楚，那么使用注释来弥补。
首先，很高兴听到您同事的代码实际上比您见过的其他代码更清晰。这意味着他可能不会用“自记录”作为懒得注释代码的借口。
自文档代码是不需要自由文本注释的代码，以便知情的读者理解它在做什么。例如，这段代码是自记录的:
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)
现在，“知情读者”这个概念是非常主观和情境化的。如果你或其他人在遵循同事的代码方面遇到了困难，那么他最好重新评估一下他对博学读者的看法。为了调用代码自文档化，必须假定对所使用的语言和库有一定程度的熟悉。
我所见过的关于编写“自文档化代码”的最佳论据是，它避免了自由文本注释与代码编写时不一致的问题。最好的批评是，虽然代码可以描述它自己在做什么以及如何做，但它不能解释为什么某些事情会以某种方式完成。
当你阅读“自文档代码”时， 你看它在做什么， 但你不能总是猜测它为什么会以那种特定的方式运行。
有大量的非编程约束 比如业务逻辑、安全性、用户需求等。
当您进行维护时，这些背景信息变得非常重要。
只是我的一小撮盐……
