我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
我忘了我从哪学来的，但是:
程序中的每一条评论都像是对读者的道歉。“很抱歉，我的代码太晦涩了，你看了都看不懂。”我们只需要接受我们并不完美，但要努力做到完美，在需要的时候道歉。
其他回答
自文档化代码是一种很好的实践，如果操作得当，可以轻松地传达代码的含义，而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。
话虽如此，评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。
自文档化代码+必要的注释将大大有助于跨团队的人员。
来自非评论阵营的一些观点。
“注释良好”(冗长)的代码更难阅读和理解。首先，有更多的文本需要扫描。它增加了理解CodeBase的认知努力——非功能性文本占用了屏幕上可以用来显示代码的空间。
注释的另一个大问题是它们不可靠——尤其是在旧的代码库中，注释腐烂比位腐烂发生得更快。
当然，还有写评论的工作。除了偶尔的一行注释之外，每次我开始注释代码时，都会有两种负罪感
这个信息需要在整个支持文档中 我需要清理我的代码
我认为——就像你们中的许多人一样——要真正实现自文档化，代码需要显示某种形式的意图。但是我很惊讶没有人提到BDD——行为驱动开发。这个想法的一部分是，你有自动化的测试(代码)来解释你的代码的意图，这是很难明显的。
Good domain modeling + good names (variabes, methods, classes) + code examples (unit tests from use cases) = self documenting software
自文档代码是一个很容易解决的问题，随着时间的推移，代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。
对我来说，以下是我努力遵循的规则:
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.
这意味着所有三种记录代码的方法都很接近，因此更有可能在代码更改时被更改，但它们所表达的内容并不重叠。
我想他可能想说的是，如果注释解释了代码的功能，那么就应该重写，以明确它的意图。这就是他所说的自文档代码。这通常意味着简单地用描述性函数名将长函数分解成逻辑上的小块。
这并不意味着代码不应该被注释。这意味着注释应该提供代码以这种方式编写的原因。
