我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
对我来说，阅读需要注释的代码就像阅读我不懂的语言的文本。我看到声明，但我不明白它是做什么的，也不明白为什么——我不得不看注释。我读了一个短语，我需要查字典来理解它的意思。
编写自记录其功能的代码通常很容易。要告诉你为什么这样做注释更合适，但即使在这里代码也可以更好。如果您在抽象的每一个层次上都理解您的系统，那么您应该尝试像这样组织代码
public Result whatYouWantToDo(){
howYouDoItStep1();
howYouDoItStep2();
return resultOfWhatYouHavDone;
}
方法名反映了你的意图，方法体解释了你如何实现你的目标。 无论如何，你不能从书名中看出整本书，所以你的系统的主要抽象仍然必须被记录下来，还有复杂的算法、非平凡的方法契约和工件。
If the code that your colleague produc is really self-documented - lucky you and him. If you think that your colleagues code needs comments - it needs. Just open the most non-trivial place in it, read it once and see if you understood everything or not. If the code is self-documented - then you should. If not - ask your colleague a question about it, after he gives you an answer ask why that answer was not documented in comments or code beforehand. He can claim that code is self-document for such smart person as him, but he anyway has to respect other team members - if your tasks require understanding of his code and his code does not explain to you everything you need to understand - it needs comments.
其他回答
所谓的自文档代码的真正问题在于它传达了它实际做的事情。虽然一些注释可以帮助别人更好地理解代码(例如，算法步骤等)，但它在一定程度上是多余的，我怀疑你能否说服你的同行。
然而，文档中真正重要的是代码中没有直接体现出来的东西:潜在的意图、假设、影响、限制等等。
能够通过快速浏览来确定代码执行X操作比能够确定代码不执行Y操作要容易得多。他必须记录Y…
你可以给他看一个代码的例子，看起来很好，很明显，但实际上并没有覆盖所有的输入基，比如，看看他是否能找到它。
已经提出的观点是，评论应该捕捉意图，但我想再深入一点。
我认为对于任何一类问题，都有一个理想的(或几乎是这样的)词汇和语法来描述它，如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考)，你就能看到它。
如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上，那么这些代码可以是自文档化的。此外，IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)
如果不能实现这个理想，如果问题不能直接映射到计算机代码上，那么就需要将两者联系起来。在我看来，这就是评论的目的。
这样，当问题发生变化时，您就可以找到相应的代码部分进行更改。
编辑:顺便说一下，我并不支持OOP方法论，即每个名词都变成一个类，每个动词都变成一个方法。我已经看过足够多的臃肿软件了。
对于许多有效的答案，我想再提供一个观点:
什么是源代码?什么是编程语言?
机器不需要源代码。他们很高兴运行组装。编程语言是为了我们的利益。我们不想写汇编。我们需要理解我们在写什么。编程就是写代码。
你能读懂你写的东西吗?
源代码不是用人类语言编写的。它已经被尝试过(例如FORTRAN)，但并不完全成功。
源代码不能有歧义。这就是为什么我们必须在其中加入比文本更多的结构。文本只适用于上下文，当我们使用文本时，我们认为这是理所当然的。源代码中的上下文总是存在的。想想c#中的“使用”。
大多数编程语言都有冗余，这样编译器就能在我们不连贯的时候发现我们。其他语言使用更多的推理，并试图消除冗余。
类型名、方法名和变量名在计算机中是不需要的。它们是供我们参考的。编译器不理解语义，这是我们要用的。
编程语言是人与机器之间的语言桥梁。它必须对我们来说是可写的，对他们来说是可读的。次要要求是它应该对我们来说是可读的。如果我们擅长语义，并且擅长构建代码，那么即使对我们来说，源代码也应该很容易阅读。最好的代码不需要注释。
但是复杂性潜伏在每个项目中，您总是需要决定将复杂性放在哪里，以及吞下哪只骆驼。这些是使用注释的地方。
我想他可能想说的是，如果注释解释了代码的功能，那么就应该重写，以明确它的意图。这就是他所说的自文档代码。这通常意味着简单地用描述性函数名将长函数分解成逻辑上的小块。
这并不意味着代码不应该被注释。这意味着注释应该提供代码以这种方式编写的原因。
自文档代码通常使用与代码所做的事情完全匹配的变量名，这样就很容易理解发生了什么
然而，这样的“自文档代码”永远不会取代注释。有时代码太复杂，自文档化代码是不够的，特别是在可维护性方面。
I once had a professor who was a firm believer in this theory In fact the best thing I ever remember him saying is "Comments are for sissies" It took all of us by surprise at first but it makes sense. However, the situation is that even though you may be able to understand what is going on in the code but someone who is less experienced that you may come behind you and not understand what is going on. This is when comments become important. I know many times that we do not believe they are important but there are very few cases where comments are unnecessary.
