我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
在编写数学代码时，我有时发现写一篇类似文章的长注释很有用，解释数学、代码使用的符号约定以及它们是如何组合在一起的。我们在这里讨论的是数百行文档。
我试着让我的代码尽可能地自文档化，但当我几个月后重新开始工作时，我确实需要阅读解释，以免把它弄得乱七八糟。
当然，这种极端的措施在大多数情况下是不必要的。我认为这个故事的寓意是:不同的代码需要不同数量的文档。有些代码可以写得很清楚，以至于不需要注释——所以要写得清楚，不要在那里使用注释!
但是很多代码确实需要注释才能有意义，所以写得越清楚越好，然后使用尽可能多的注释……
其他回答
在我看来，任何代码都应该是自记录的。在良好的、自文档化的代码中，您不必解释每一行，因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!)，所以如果您的同事
为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图，或者代码在更高抽象级别上做了什么(例如，找到所有大于10mb的文件，而不是遍历目录中的所有文件，测试文件大小是否大于10mb，如果为真则返回)
在我看来，他的代码和文档都很好。请注意，自文档化的代码并不意味着不应该有注释，而只是不应该有不必要的注释。然而，问题是，通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解，那么它就不是真正的自文档化。
为什么代码之外的额外注释可能会更清晰，原因如下:
您正在查看的代码是自动生成的，因此对代码的任何编辑都可能在下次编译项目时失败 一个不太直接的实现被用来换取性能的提高(展开循环，为昂贵的计算创建查找表，等等)。
我忘了我从哪学来的，但是:
程序中的每一条评论都像是对读者的道歉。“很抱歉，我的代码太晦涩了，你看了都看不懂。”我们只需要接受我们并不完美，但要努力做到完美，在需要的时候道歉。
This is an excellent question. It traces back to the first programming language that allowed comments, I'm sure. The code certainly should be as self-documenting as possible. Comments that point out the obvious, should be eliminated. Comments that make it easier to understand the intent, purpose, and use of a given method or section of code can be invaluable to those of us dolts that may be less familiar with the language or code in question. Structured comments that allow for the generation of API documentation are a good example. Just don't comment an IF statement that checks to see if a checkbox is checked and tell me that you're checking to see if the checkbox is checked. Restating the obvious in a comment is the worst waste keystrokes in our universe.
//For example, the above text deals with what is a useful comment
我会扭转局面。
问问自己在他的代码中有什么不理解的，然后让他把这些记录下来。也许你也可以告诉我们一些。
