我有一个同事,他坚持认为他的代码不需要注释,这是“自文档”。

我已经审阅了他的代码,虽然它比我看到的其他人编写的代码更清晰,但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。

帮我理解一下他的观点。

什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下,它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子

也许这只是我自身的局限性,但我看不出这怎么能成为一种好的练习。

这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点,但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点,才能说服他。如果你有必要,可以提出一个新的问题,但不要在这里争论。

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


当前回答

自文档代码是非常清晰的代码,以至于不需要注释。我举个小例子:

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

注释没什么用,因为代码很清楚。文档是一个很好的实践,但是额外的文档会给代码增加不必要的干扰。你的同事需要知道的是,不是每个人都能阅读别人的代码并了解所有的细节。

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

如果没有注释,最后一个片段将很难破译。你可以想象其他更做作的例子。

其他回答

在编写数学代码时,我有时发现写一篇类似文章的长注释很有用,解释数学、代码使用的符号约定以及它们是如何组合在一起的。我们在这里讨论的是数百行文档。

我试着让我的代码尽可能地自文档化,但当我几个月后重新开始工作时,我确实需要阅读解释,以免把它弄得乱七八糟。

当然,这种极端的措施在大多数情况下是不必要的。我认为这个故事的寓意是:不同的代码需要不同数量的文档。有些代码可以写得很清楚,以至于不需要注释——所以要写得清楚,不要在那里使用注释!

但是很多代码确实需要注释才能有意义,所以写得越清楚越好,然后使用尽可能多的注释……

在我看来,任何代码都应该是自记录的。在良好的、自文档化的代码中,您不必解释每一行,因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!),所以如果您的同事

为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图,或者代码在更高抽象级别上做了什么(例如,找到所有大于10mb的文件,而不是遍历目录中的所有文件,测试文件大小是否大于10mb,如果为真则返回)

在我看来,他的代码和文档都很好。请注意,自文档化的代码并不意味着不应该有注释,而只是不应该有不必要的注释。然而,问题是,通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解,那么它就不是真正的自文档化。

您可能希望向您的同事指出的一件事是,无论他的代码是如何自我记录的,如果考虑并放弃了其他替代方法,那么该信息将丢失,除非他用该信息注释代码。有时,了解考虑了替代方案以及为什么不选择它同样重要,并且代码注释最有可能随着时间的推移而幸存下来。

我曾经和一个家伙一起工作,他打算把金融套件卖给一家大公司。他们坚持让他记录源代码,他写了一个30多页的汇编程序,并说“这是有记录的,看”——然后他翻到第13页,有一条评论“bump counter by one”。 伟大的产品,伟大的实现者,但是……

无论如何,在我看来,上面的重要评论是为了设置上下文。这段代码是自记录的:

> from BeautifulSoup import
> BeautifulSoup, Tag def
> replace_a_href_with_span(soup):
>     links = soup.findAll("a")
>     for link in links:
>         tag = Tag(soup, "span", [("class", "looksLikeLink")])
>         tag.contents = link.contents
>         link.replaceWith(tag)

但是,就我个人而言,需要一个背景来充分理解它。

既然这是关于注释和代码的,那么让我们来看一些实际的代码。比较下面的典型代码:

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.

在最后一个例子中,当变量应该被描述性地命名时,就会使用注释,当我们可以清楚地看到操作是什么时,就会总结操作的结果。无论如何,我更喜欢自文档化的第二个示例,也许这就是您的朋友所说的自文档化代码。

我会说,这取决于你所做的事情的背景。对我来说,在这种情况下,自编文档的代码可能就足够了,但是详细描述所做事情(在本例中是方程)背后的方法的注释也很有用。