我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
当你阅读“自文档代码”时， 你看它在做什么， 但你不能总是猜测它为什么会以那种特定的方式运行。
有大量的非编程约束 比如业务逻辑、安全性、用户需求等。
当您进行维护时，这些背景信息变得非常重要。
只是我的一小撮盐……
其他回答
如果没有注释，代码就不完全清晰，那么还有改进代码的空间。
我并不是说“不要评论不清楚的代码”。我说的是“让你的代码清晰”。
如果你最终让你的代码在某种程度上不清楚，那么使用注释来弥补。
我认为自记录代码是注释的一个很好的替代品。如果您需要注释来解释代码是如何或为什么是这样的，那么您应该修改函数或变量名以使其更具解释性。这可能取决于编码器是否会用注释或重命名一些变量和函数并重构代码来弥补不足。
但是，它并不能真正取代您的文档，因为文档是您提供给其他人用来解释如何使用您的系统的，而不是它是如何工作的。
编辑:我(可能还有其他所有人)应该有一个数字信号处理(DSP)应用程序应该很好地注释的规定。这主要是因为DSP应用程序本质上是2 for循环，提供了数组的值和添加/乘以/等等所说的值…要更改程序，您需要更改其中一个数组中的值…需要一些评论来说明在这种情况下你在做什么;)
这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。
如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:
BisectionSearch
BinarySearch
二进制斩
这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。
已经提出的观点是，评论应该捕捉意图，但我想再深入一点。
我认为对于任何一类问题，都有一个理想的(或几乎是这样的)词汇和语法来描述它，如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考)，你就能看到它。
如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上，那么这些代码可以是自文档化的。此外，IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)
如果不能实现这个理想，如果问题不能直接映射到计算机代码上，那么就需要将两者联系起来。在我看来，这就是评论的目的。
这样，当问题发生变化时，您就可以找到相应的代码部分进行更改。
编辑:顺便说一下，我并不支持OOP方法论，即每个名词都变成一个类，每个动词都变成一个方法。我已经看过足够多的臃肿软件了。
我想他可能想说的是，如果注释解释了代码的功能，那么就应该重写，以明确它的意图。这就是他所说的自文档代码。这通常意味着简单地用描述性函数名将长函数分解成逻辑上的小块。
这并不意味着代码不应该被注释。这意味着注释应该提供代码以这种方式编写的原因。
