我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
如果没有注释，代码就不完全清晰，那么还有改进代码的空间。
我并不是说“不要评论不清楚的代码”。我说的是“让你的代码清晰”。
如果你最终让你的代码在某种程度上不清楚，那么使用注释来弥补。
其他回答
以下是我对你的问题的最佳回答。
自文档代码是用类、方法、函数和变量名称清晰编写的代码，这些名称使其意图和函数易于理解。如果做得好，它就是文档。
它可以取代注释和文档完善的代码，但我很少见到它。很多时候，程序员认为他们已经足够好了，但是打倒他们的最好方法是开始问问题。如果他们不得不开始解释太多，那么他们的代码就不够清晰。您不应该阅读代码来了解它的功能。
在某些情况下，这样做会更好。如果代码又小又简单，那么添加文档可能会把事情弄得乱七八糟。
包含算法的代码应该包含注释。大多数时候，即使是最初的程序员也不记得几个月前他们在写一个长函数时到底在想什么。
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.
有人曾经说过
1)只对难以理解的代码写注释。 2)尽量不要编写难以理解的代码。
自文档代码是一个很容易解决的问题，随着时间的推移，代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。
对我来说，以下是我努力遵循的规则:
Code should be as easy and clear to read as possible. Comments should give reasons for design decisions I took, like: why do I use this algorithm, or limitations the code has, like: does not work when ... (this should be handled in a contract/assertion in the code) (usually within the function/procedure). Documentation should list usage (calling converntions), side effects, possible return values. It can be extracted from code using tools like jDoc or xmlDoc. It therefore usually is outside the function/procedure, but close to the code it describes.
这意味着所有三种记录代码的方法都很接近，因此更有可能在代码更改时被更改，但它们所表达的内容并不重叠。
在我工作的一家公司里，一个程序员把下面的文字粘在了她的显示器上。
“就像维护代码的人是一个知道你住在哪里的杀人狂一样，记录你的代码。”
