我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
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.
为了文档而编写文档可能会浪费时间，因为文档需要维护，以便与代码库保持同步。如果没有人会从阅读中受益，那就不要写。
其他回答
自文档化代码是一种很好的实践，如果操作得当，可以轻松地传达代码的含义，而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。
话虽如此，评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。
自文档化代码+必要的注释将大大有助于跨团队的人员。
自我记录代码是愚蠢的。任何在几周、几个月或几年之后不得不重新访问代码的人都知道这一点(对我来说是几天)。(也许推广这个想法的人还很幼稚!?! ! !)
使用有意义的、描述性的数据名称，聪明地分解代码，并给自己留下提示，告诉自己为什么要这么做，这样你的生活就会更丰富、更充实。
尽管……我确实读过一句比尔·盖茨说过的话:“代码就是文档。”
图。
自文档代码通常使用与代码所做的事情完全匹配的变量名，这样就很容易理解发生了什么
然而，这样的“自文档代码”永远不会取代注释。有时代码太复杂，自文档化代码是不够的，特别是在可维护性方面。
I once had a professor who was a firm believer in this theory In fact the best thing I ever remember him saying is "Comments are for sissies" It took all of us by surprise at first but it makes sense. However, the situation is that even though you may be able to understand what is going on in the code but someone who is less experienced that you may come behind you and not understand what is going on. This is when comments become important. I know many times that we do not believe they are important but there are very few cases where comments are unnecessary.
我认为，质疑某一行代码是否具有自文档性是有意义的，但最终，如果你不理解一段代码的结构和功能，那么大多数时候注释是没有用的。以amdfan的“正确注释”代码片段为例:
/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
这段代码很好，但下面的代码在大多数现代软件系统中同样具有丰富的信息，并且明确认识到使用牛顿计算是一种选择，如果其他一些物理范式更合适，可能会被改变:
const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);
根据我个人的经验，很少有绝对需要注释的“正常”编码情况。举个例子，你有多频繁地使用自己的算法?基本上，其他一切都是构建系统的问题，以便编码器能够理解正在使用的结构以及驱动系统使用这些特定结构的选择。
已经提出的观点是，评论应该捕捉意图，但我想再深入一点。
我认为对于任何一类问题，都有一个理想的(或几乎是这样的)词汇和语法来描述它，如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考)，你就能看到它。
如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上，那么这些代码可以是自文档化的。此外，IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)
如果不能实现这个理想，如果问题不能直接映射到计算机代码上，那么就需要将两者联系起来。在我看来，这就是评论的目的。
这样，当问题发生变化时，您就可以找到相应的代码部分进行更改。
编辑:顺便说一下，我并不支持OOP方法论，即每个名词都变成一个类，每个动词都变成一个方法。我已经看过足够多的臃肿软件了。
