我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
对于许多有效的答案，我想再提供一个观点:
什么是源代码?什么是编程语言?
机器不需要源代码。他们很高兴运行组装。编程语言是为了我们的利益。我们不想写汇编。我们需要理解我们在写什么。编程就是写代码。
你能读懂你写的东西吗?
源代码不是用人类语言编写的。它已经被尝试过(例如FORTRAN)，但并不完全成功。
源代码不能有歧义。这就是为什么我们必须在其中加入比文本更多的结构。文本只适用于上下文，当我们使用文本时，我们认为这是理所当然的。源代码中的上下文总是存在的。想想c#中的“使用”。
大多数编程语言都有冗余，这样编译器就能在我们不连贯的时候发现我们。其他语言使用更多的推理，并试图消除冗余。
类型名、方法名和变量名在计算机中是不需要的。它们是供我们参考的。编译器不理解语义，这是我们要用的。
编程语言是人与机器之间的语言桥梁。它必须对我们来说是可写的，对他们来说是可读的。次要要求是它应该对我们来说是可读的。如果我们擅长语义，并且擅长构建代码，那么即使对我们来说，源代码也应该很容易阅读。最好的代码不需要注释。
但是复杂性潜伏在每个项目中，您总是需要决定将复杂性放在哪里，以及吞下哪只骆驼。这些是使用注释的地方。
其他回答
我忘了我从哪学来的，但是:
程序中的每一条评论都像是对读者的道歉。“很抱歉，我的代码太晦涩了，你看了都看不懂。”我们只需要接受我们并不完美，但要努力做到完美，在需要的时候道歉。
首先，考虑下面的代码片段:
/**
* 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;
}
不过，对于简单的代码，我更喜欢没有注释。意图和整体组织最好在代码之外的单独文档中解释。
Self documenting code is code that is trivially easy to understand. Variable naming goes a long way to making code self documenting, but i find the best tactic is to break any complicated logic down into tiny little chunks and refactor that information into seperate methods with verbose and informative names. Then your complicated methods become simply a list of steps to be performed. The tiny private helper methods then are documented sufficiently by their own method name and the complicated methods are documented as a sequence of abstract steps to be performed. In practice this strategy cannot always be applied perfectly so comments are still very useful. Plus you should never completely abandon any tool which will help you write code that is easier to understand.
我想他可能想说的是，如果注释解释了代码的功能，那么就应该重写，以明确它的意图。这就是他所说的自文档代码。这通常意味着简单地用描述性函数名将长函数分解成逻辑上的小块。
这并不意味着代码不应该被注释。这意味着注释应该提供代码以这种方式编写的原因。
在我看来，任何代码都应该是自记录的。在良好的、自文档化的代码中，您不必解释每一行，因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!)，所以如果您的同事
为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图，或者代码在更高抽象级别上做了什么(例如，找到所有大于10mb的文件，而不是遍历目录中的所有文件，测试文件大小是否大于10mb，如果为真则返回)
在我看来，他的代码和文档都很好。请注意，自文档化的代码并不意味着不应该有注释，而只是不应该有不必要的注释。然而，问题是，通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解，那么它就不是真正的自文档化。
