我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
代码本身总是对代码功能的最新解释，但在我看来，它很难解释意图，这是注释最重要的方面。如果代码写得很好，我们已经知道代码的功能，我们只需要知道它到底为什么这样做!
其他回答
我曾经和一个家伙一起工作，他打算把金融套件卖给一家大公司。他们坚持让他记录源代码，他写了一个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)
但是，就我个人而言，需要一个背景来充分理解它。
我会扭转局面。
问问自己在他的代码中有什么不理解的，然后让他把这些记录下来。也许你也可以告诉我们一些。
区别在于“什么”和“如何”。
您应该记录一个例程做了什么。 你不应该记录它是如何做到的，除非特殊情况(例如，参考一篇特定的算法论文)。这应该是自我记录的。
这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。
如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:
BisectionSearch
BinarySearch
二进制斩
这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。
自文档代码是一个很容易解决的问题，随着时间的推移，代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。
对我来说，以下是我努力遵循的规则:
Code should be as easy and clear to read as possible. Comments should give reasons for design decisions I took, like: why do I use this algorithm, or limitations the code has, like: does not work when ... (this should be handled in a contract/assertion in the code) (usually within the function/procedure). Documentation should list usage (calling converntions), side effects, possible return values. It can be extracted from code using tools like jDoc or xmlDoc. It therefore usually is outside the function/procedure, but close to the code it describes.
这意味着所有三种记录代码的方法都很接近，因此更有可能在代码更改时被更改，但它们所表达的内容并不重叠。
