我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
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
其他回答
我很惊讶居然没有人提出“识字编程”，这是一种由德克萨斯州的Donald E. Knuth在1981年提出的技术，并因《计算机编程的艺术》而闻名。
前提很简单:既然代码必须被人类理解，注释被编译器简单地扔掉，为什么不给每个人他们需要的东西——对代码意图的完整文本描述，不受编程语言要求的限制，为人类读者和编译器提供纯代码。
识字编程工具通过为文档提供特殊标记来实现这一点，这些标记告诉工具哪些部分应该是源代码，哪些部分是文本。该程序随后从文档中提取源代码部分并汇编代码文件。
我在它的网页上找到了一个例子:http://moonflare.com/code/select/select.nw或HTML版本http://moonflare.com/code/select/select.html
如果你能在图书馆找到Knuth的书(Donald E. Knuth，文学程序设计，斯坦福，加利福尼亚:语言和信息研究中心，1992,CSLI课堂笔记，没有。27.)你应该读一读。
这是自文档化的代码，包括推理等。即使是一份很好的文件， 其他一切都是写得很好的评论:-)
为什么代码之外的额外注释可能会更清晰，原因如下:
您正在查看的代码是自动生成的，因此对代码的任何编辑都可能在下次编译项目时失败 一个不太直接的实现被用来换取性能的提高(展开循环，为昂贵的计算创建查找表，等等)。
我相信您应该始终努力实现自文档化代码，因为它确实使代码阅读变得更容易。然而，你也必须务实。
例如，我通常为每个类成员添加注释(为此我使用文档注释)。这描述了成员应该做什么，而不是如何做。我发现，当我阅读代码，特别是旧代码时，这有助于我快速记住成员是用来做什么的，我也发现这比阅读代码和解决它更容易，特别是当代码流跳跃相当多的时候。
这只是我的个人观点。我知道很多人在工作时根本没有评论，他们认为这没有问题。然而，我曾经问过某人关于他们六个月前写的一个方法，他们不得不思考几分钟来告诉我它到底是做什么的。如果方法是注释的，这不是问题。
最后，您必须记住，注释和代码一样都是系统的一部分。在重构和更改功能时，还必须更新注释。这是反对使用注释的一个论点，因为如果它们不正确，它们比无用更糟糕。
在我看来，任何代码都应该是自记录的。在良好的、自文档化的代码中，您不必解释每一行，因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!)，所以如果您的同事
为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图，或者代码在更高抽象级别上做了什么(例如，找到所有大于10mb的文件，而不是遍历目录中的所有文件，测试文件大小是否大于10mb，如果为真则返回)
在我看来，他的代码和文档都很好。请注意，自文档化的代码并不意味着不应该有注释，而只是不应该有不必要的注释。然而，问题是，通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解，那么它就不是真正的自文档化。
这里的输入似乎非常复杂:)
我使用伪代码编程过程进行新的开发，这实际上使我的代码自文档化。我只在写新代码时才开始写伪代码，然后在上面扩展。我不是说这是最佳实践或类似的东西，我只是强调一个我认为有用的技巧，如果你知道你的代码需要大量的文档，如果它要交给第三方，审查者等等……它偶尔也会在我还没写一行代码的时候就给我指出一些问题。
' check database is available
' if it is then allow the procedure
' if it isnt roll back and tidy up
' move onto something else
变成了;
' check database is available
if checkDBStateResult(currentDB) = Open then
' if it is then allow the procedure
proc.Ok = True
else
' if it isnt roll back
proc.Ok = False
CleanUp()
end if
