我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
所谓的自文档代码的真正问题在于它传达了它实际做的事情。虽然一些注释可以帮助别人更好地理解代码(例如，算法步骤等)，但它在一定程度上是多余的，我怀疑你能否说服你的同行。
然而，文档中真正重要的是代码中没有直接体现出来的东西:潜在的意图、假设、影响、限制等等。
能够通过快速浏览来确定代码执行X操作比能够确定代码不执行Y操作要容易得多。他必须记录Y…
你可以给他看一个代码的例子，看起来很好，很明显，但实际上并没有覆盖所有的输入基，比如，看看他是否能找到它。
其他回答
在我看来，任何代码都应该是自记录的。在良好的、自文档化的代码中，您不必解释每一行，因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!)，所以如果您的同事
为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图，或者代码在更高抽象级别上做了什么(例如，找到所有大于10mb的文件，而不是遍历目录中的所有文件，测试文件大小是否大于10mb，如果为真则返回)
在我看来，他的代码和文档都很好。请注意，自文档化的代码并不意味着不应该有注释，而只是不应该有不必要的注释。然而，问题是，通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解，那么它就不是真正的自文档化。
这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。
如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:
BisectionSearch
BinarySearch
二进制斩
这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。
自文档化代码是一种很好的实践，如果操作得当，可以轻松地传达代码的含义，而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。
话虽如此，评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。
自文档化代码+必要的注释将大大有助于跨团队的人员。
有人曾经说过
1)只对难以理解的代码写注释。 2)尽量不要编写难以理解的代码。
代码本身总是对代码功能的最新解释，但在我看来，它很难解释意图，这是注释最重要的方面。如果代码写得很好，我们已经知道代码的功能，我们只需要知道它到底为什么这样做!
