记录代码并可以替代有据可查的代码？
我有一位同事坚持认为他的代码不需要评论，这是“自我记录”。
我已经回顾了他的代码，虽然它比我见过的其他代码更清晰，但我仍然不同意自编档代码是完整且有用的，以及经过评论和记录的代码。
帮助我理解他的观点。
也许这只是我自己的限制，但我不认为这是一种好的做法。
这并不意味着一个论点 - 请不要提出为什么评论良好并且文档化的代码是重中之重的原因 - 有很多资源表明这一点，但他们对我的同行没有说服力。 我相信我需要更充分地理解他的观点，否则就说服他。 如果你必须开始一个新问题，但不要在这里争论。
哇，快回复！ 请阅读所有现有答案，并提供答案意见，而不是添加新的答案，除非您的答案与此处的所有其他答案完全不同。
另外，那些反对自我记录代码的人 - 这些主要是为了帮助我理解自我记录代码传播者的观点（即积极方面）。 我希望如果你不停留在话题上，别人会低估你。
在我看来，任何代码都应该是自我记录的。 在良好的，自我记录的代码中，你不必解释每一行，因为每个标识符（变量，方法，类）都有明确的语义名称。 如果有更多的评论意见实际上使得阅读代码变得更加困难（！），所以如果你的同事
在我看来，他的代码和文档很好。 请注意，自记录代码并不意味着应该没有意见，但只应该有任何不必要的评论。 然而，通过阅读代码（包括注释和文档注释）应该立即理解代码的作用和原因。 如果“自我记录”代码比注释代码要花费更长的时间才能理解，那么它并不是真正的自我记录。
那么，因为这是关于注释和代码的，我们来看看一些实际的代码。 比较这个典型的代码：
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.
在最后一个例子中，当变量应该被描述性地命名时，使用注释，而当我们可以清楚地看到操作是什么时，总结操作的结果。 我更喜欢这个自我记录的第二个例子，可能这就是你的朋友在说自我记录的代码时所谈论的内容。
我会说这取决于你在做什么的背景。 对我而言，自编的代码在这种情况下可能就足够了，但是详细说明背后所做的方法（在本例中是方程式）的评论也很有用。
代码本身始终是您代码的最新解释，但在我看来，它很难解释意图，这是意见最重要的方面。 如果编写得当，我们已经知道代码的作用了，我们只需要知道为什么它能做到这一点！
链接地址: http://www.djcxy.com/p/20585.html上一篇: documenting code and can it replace well documented code?
下一篇: What is the best comment in source code you have ever encountered?