我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
首先，考虑下面的代码片段:
/**
* 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;
}
不过，对于简单的代码，我更喜欢没有注释。意图和整体组织最好在代码之外的单独文档中解释。
其他回答
不管纯粹的自文档代码是否可以实现，有一些事情是人们应该做的:
Never have code that is "surprising". Ie. don't use silly macro's to redefine things etc. Don't misuse operator overloading, don't try to be smart on this. Split away code at the right point. Use proper abstractions. Instead of inlining a rolling buffer (a buffer with fixed length, with two pointers that gets items added at one end and removed at the other), use an abstraction with a proper name. Keep function complexity low. If it gets too long or complex, try to split it out into other other functions.
当实现特定的复杂算法时，添加描述算法的文档(或链接)。但在这种情况下，要努力去除不必要的复杂性，增加易读性，因为很容易犯错误。
我认为自记录代码是注释的一个很好的替代品。如果您需要注释来解释代码是如何或为什么是这样的，那么您应该修改函数或变量名以使其更具解释性。这可能取决于编码器是否会用注释或重命名一些变量和函数并重构代码来弥补不足。
但是，它并不能真正取代您的文档，因为文档是您提供给其他人用来解释如何使用您的系统的，而不是它是如何工作的。
编辑:我(可能还有其他所有人)应该有一个数字信号处理(DSP)应用程序应该很好地注释的规定。这主要是因为DSP应用程序本质上是2 for循环，提供了数组的值和添加/乘以/等等所说的值…要更改程序，您需要更改其中一个数组中的值…需要一些评论来说明在这种情况下你在做什么;)
自文档化代码是一种很好的实践，如果操作得当，可以轻松地传达代码的含义，而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。
话虽如此，评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。
自文档化代码+必要的注释将大大有助于跨团队的人员。
首先，很高兴听到您同事的代码实际上比您见过的其他代码更清晰。这意味着他可能不会用“自记录”作为懒得注释代码的借口。
自文档代码是不需要自由文本注释的代码，以便知情的读者理解它在做什么。例如，这段代码是自记录的:
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)
现在，“知情读者”这个概念是非常主观和情境化的。如果你或其他人在遵循同事的代码方面遇到了困难，那么他最好重新评估一下他对博学读者的看法。为了调用代码自文档化，必须假定对所使用的语言和库有一定程度的熟悉。
我所见过的关于编写“自文档化代码”的最佳论据是，它避免了自由文本注释与代码编写时不一致的问题。最好的批评是，虽然代码可以描述它自己在做什么以及如何做，但它不能解释为什么某些事情会以某种方式完成。
这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。
如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:
BisectionSearch
BinarySearch
二进制斩
这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。
