我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
好的设计结构有助于指出，有些函数是通用的，有些是随机的业务逻辑，即使你没有评论说“这个函数是通用的”。
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.
还要考虑功能的可跟踪性。当你有了你的手册，那么你应该能够追踪到源代码的特性，并返回更好的可维护性。手册和规范与编程没有太大关系，但它们与软件工程有关。软件越大，需要的工程设计就越多。
其他回答
这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。
如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:
BisectionSearch
BinarySearch
二进制斩
这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。
对于许多有效的答案，我想再提供一个观点:
什么是源代码?什么是编程语言?
机器不需要源代码。他们很高兴运行组装。编程语言是为了我们的利益。我们不想写汇编。我们需要理解我们在写什么。编程就是写代码。
你能读懂你写的东西吗?
源代码不是用人类语言编写的。它已经被尝试过(例如FORTRAN)，但并不完全成功。
源代码不能有歧义。这就是为什么我们必须在其中加入比文本更多的结构。文本只适用于上下文，当我们使用文本时，我们认为这是理所当然的。源代码中的上下文总是存在的。想想c#中的“使用”。
大多数编程语言都有冗余，这样编译器就能在我们不连贯的时候发现我们。其他语言使用更多的推理，并试图消除冗余。
类型名、方法名和变量名在计算机中是不需要的。它们是供我们参考的。编译器不理解语义，这是我们要用的。
编程语言是人与机器之间的语言桥梁。它必须对我们来说是可写的，对他们来说是可读的。次要要求是它应该对我们来说是可读的。如果我们擅长语义，并且擅长构建代码，那么即使对我们来说，源代码也应该很容易阅读。最好的代码不需要注释。
但是复杂性潜伏在每个项目中，您总是需要决定将复杂性放在哪里，以及吞下哪只骆驼。这些是使用注释的地方。
有人曾经说过
1)只对难以理解的代码写注释。 2)尽量不要编写难以理解的代码。
代码本身总是对代码功能的最新解释，但在我看来，它很难解释意图，这是注释最重要的方面。如果代码写得很好，我们已经知道代码的功能，我们只需要知道它到底为什么这样做!
既然这是关于注释和代码的，那么让我们来看一些实际的代码。比较下面的典型代码:
float a, b, c; a=9.81; b=5; c= .5*a*(b^2);
到这个显示正在执行的操作的自文档代码:
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
然后是这个文档代码，它更好地解释了为什么要这样做:
/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
最终版本的代码作为文档，不需要注释:
float computeDisplacement(float timeInSeconds) {
const float gravitationalForce = 9.81;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
return displacement;
}
下面是一个糟糕评论风格的例子:
const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.
在最后一个例子中，当变量应该被描述性地命名时，就会使用注释，当我们可以清楚地看到操作是什么时，就会总结操作的结果。无论如何，我更喜欢自文档化的第二个示例，也许这就是您的朋友所说的自文档化代码。
我会说，这取决于你所做的事情的背景。对我来说，在这种情况下，自编文档的代码可能就足够了，但是详细描述所做事情(在本例中是方程)背后的方法的注释也很有用。
