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

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

帮我理解一下他的观点。

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

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

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

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


当前回答

我认为——就像你们中的许多人一样——要真正实现自文档化,代码需要显示某种形式的意图。但是我很惊讶没有人提到BDD——行为驱动开发。这个想法的一部分是,你有自动化的测试(代码)来解释你的代码的意图,这是很难明显的。

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

其他回答

来自非评论阵营的一些观点。

“注释良好”(冗长)的代码更难阅读和理解。首先,有更多的文本需要扫描。它增加了理解CodeBase的认知努力——非功能性文本占用了屏幕上可以用来显示代码的空间。

注释的另一个大问题是它们不可靠——尤其是在旧的代码库中,注释腐烂比位腐烂发生得更快。

当然,还有写评论的工作。除了偶尔的一行注释之外,每次我开始注释代码时,都会有两种负罪感

这个信息需要在整个支持文档中 我需要清理我的代码

我曾经和一个家伙一起工作,他打算把金融套件卖给一家大公司。他们坚持让他记录源代码,他写了一个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)

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

自文档代码是一个很容易解决的问题,随着时间的推移,代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。

对我来说,以下是我努力遵循的规则:

Code should be as easy and clear to read as possible. Comments should give reasons for design decisions I took, like: why do I use this algorithm, or limitations the code has, like: does not work when ... (this should be handled in a contract/assertion in the code) (usually within the function/procedure). Documentation should list usage (calling converntions), side effects, possible return values. It can be extracted from code using tools like jDoc or xmlDoc. It therefore usually is outside the function/procedure, but close to the code it describes.

这意味着所有三种记录代码的方法都很接近,因此更有可能在代码更改时被更改,但它们所表达的内容并不重叠。

我很惊讶居然没有人提出“识字编程”,这是一种由德克萨斯州的Donald E. Knuth在1981年提出的技术,并因《计算机编程的艺术》而闻名。

前提很简单:既然代码必须被人类理解,注释被编译器简单地扔掉,为什么不给每个人他们需要的东西——对代码意图的完整文本描述,不受编程语言要求的限制,为人类读者和编译器提供纯代码。

识字编程工具通过为文档提供特殊标记来实现这一点,这些标记告诉工具哪些部分应该是源代码,哪些部分是文本。该程序随后从文档中提取源代码部分并汇编代码文件。

我在它的网页上找到了一个例子:http://moonflare.com/code/select/select.nw或HTML版本http://moonflare.com/code/select/select.html

如果你能在图书馆找到Knuth的书(Donald E. Knuth,文学程序设计,斯坦福,加利福尼亚:语言和信息研究中心,1992,CSLI课堂笔记,没有。27.)你应该读一读。

这是自文档化的代码,包括推理等。即使是一份很好的文件, 其他一切都是写得很好的评论:-)

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

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.

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

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