我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
I think its a matter of the right amount of documentation, rather than all or none. If the parameters to a function are well named, you often don't have to say exactly what they are, e.g. char *CustomerName is pretty obvious. If you use assert value ranges for parameters, you don't have to document those ranges as well. IMO, documentation should cover everything which is less than obvious and hence needs some explanation, and most code needs some documentation. Personally, I'd rather see an illustrative example of how a given function works than descriptive documentation, in most cases.
为了文档而编写文档可能会浪费时间，因为文档需要维护，以便与代码库保持同步。如果没有人会从阅读中受益，那就不要写。
其他回答
首先，考虑下面的代码片段:
/**
* 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.
好的设计结构有助于指出，有些函数是通用的，有些是随机的业务逻辑，即使你没有评论说“这个函数是通用的”。
We should not forget about design and specification documentation though. Those have or at least should have much of the texts that are not necessarily needed in comments. Software often have also user manuals and other description documents, and those should be in sync with what the program does. The situation is not great if the user has to find out what the software does from the source code instead of a manual. So self documenting code still doesn't mean that the actual software has been documented.
还要考虑功能的可跟踪性。当你有了你的手册，那么你应该能够追踪到源代码的特性，并返回更好的可维护性。手册和规范与编程没有太大关系，但它们与软件工程有关。软件越大，需要的工程设计就越多。
我会扭转局面。
问问自己在他的代码中有什么不理解的，然后让他把这些记录下来。也许你也可以告诉我们一些。
区别在于“什么”和“如何”。
您应该记录一个例程做了什么。 你不应该记录它是如何做到的，除非特殊情况(例如，参考一篇特定的算法论文)。这应该是自我记录的。
