documentation - 什么是自文档化代码？它可以取代有据可查的代码吗？

Question

我有一位同事坚持认为他的代码不需要注释，它是“ self 文档化”。

我已经审查了他的代码，虽然它比我见过的其他人生成的代码更清晰，但我仍然不同意自记录代码与经过注释和记录的代码一样完整和有用。

帮助我理解他的观点。

• 什么是自文档代码
• 它真的可以取代注释良好且记录良好的代码吗
• 在某些情况下它是否比有详细记录和注释的代码更好
• 是否存在代码无法在没有注释的情况下进行 self 记录的示例

也许这只是我自己的局限性，但我不认为这是一个好的做法。

这并不是一个争论 - 请不要提出为什么注释和记录良好的代码具有高优先级的原因 - 有很多资源表明了这一点，但它们并不能令我的同行信服。我相信我需要更充分地理解他的观点才能说服他。如果必须的话，可以提出一个新问题，但不要在这里争论。

此外，那些反对自记录代码的人 - 这主要是为了帮助我理解自记录代码传播者的观点(即积极的方面)。

Answer 1

好吧，由于这是关于注释和代码的，所以让我们看一些实际的代码。比较一下这个典型的代码:

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.

在最后一个例子中，当变量应该被描述性地命名时使用注释，当我们可以清楚地看到操作是什么时，操作的结果被总结。与任何一天相比，我更喜欢自记录的第二个示例，也许这就是您的 friend 在说自记录代码时所谈论的内容。

我想说这取决于你正在做的事情的背景。对我来说，在这种情况下，自记录的代码可能就足够了，但是详细说明完成背后的方法(在本例中为方程)的注释也很有用。