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

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

帮我理解一下他的观点。

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

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

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

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


当前回答

“自文档化”代码背后的思想是,代码中的实际程序逻辑非常清楚,不仅可以向阅读代码的人解释代码在做什么,还可以向他们解释为什么要这样做。

在我看来,真正的自文档代码的想法是一个神话。代码可以告诉您正在发生的事情背后的逻辑,但它不能解释为什么要以某种方式完成,特别是如果有不止一种方法来解决问题。仅仅因为这个原因,它永远不能取代注释良好的代码。

其他回答

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

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.

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

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

这里的输入似乎非常复杂:)

我使用伪代码编程过程进行新的开发,这实际上使我的代码自文档化。我只在写新代码时才开始写伪代码,然后在上面扩展。我不是说这是最佳实践或类似的东西,我只是强调一个我认为有用的技巧,如果你知道你的代码需要大量的文档,如果它要交给第三方,审查者等等……它偶尔也会在我还没写一行代码的时候就给我指出一些问题。

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

变成了;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if

“自文档化”代码背后的思想是,代码中的实际程序逻辑非常清楚,不仅可以向阅读代码的人解释代码在做什么,还可以向他们解释为什么要这样做。

在我看来,真正的自文档代码的想法是一个神话。代码可以告诉您正在发生的事情背后的逻辑,但它不能解释为什么要以某种方式完成,特别是如果有不止一种方法来解决问题。仅仅因为这个原因,它永远不能取代注释良好的代码。

首先,很高兴听到您同事的代码实际上比您见过的其他代码更清晰。这意味着他可能不会用“自记录”作为懒得注释代码的借口。

自文档代码是不需要自由文本注释的代码,以便知情的读者理解它在做什么。例如,这段代码是自记录的:

print "Hello, World!"

这也是:

factorial n = product [1..n]

这也是:

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)

现在,“知情读者”这个概念是非常主观和情境化的。如果你或其他人在遵循同事的代码方面遇到了困难,那么他最好重新评估一下他对博学读者的看法。为了调用代码自文档化,必须假定对所使用的语言和库有一定程度的熟悉。

我所见过的关于编写“自文档化代码”的最佳论据是,它避免了自由文本注释与代码编写时不一致的问题。最好的批评是,虽然代码可以描述它自己在做什么以及如何做,但它不能解释为什么某些事情会以某种方式完成。

为什么代码之外的额外注释可能会更清晰,原因如下:

您正在查看的代码是自动生成的,因此对代码的任何编辑都可能在下次编译项目时失败 一个不太直接的实现被用来换取性能的提高(展开循环,为昂贵的计算创建查找表,等等)。