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

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

帮我理解一下他的观点。

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

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

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

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


当前回答

我很惊讶居然没有人提出“识字编程”,这是一种由德克萨斯州的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.)你应该读一读。

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

其他回答

我忘了我从哪学来的,但是:

程序中的每一条评论都像是对读者的道歉。“很抱歉,我的代码太晦涩了,你看了都看不懂。”我们只需要接受我们并不完美,但要努力做到完美,在需要的时候道歉。

This is an excellent question. It traces back to the first programming language that allowed comments, I'm sure. The code certainly should be as self-documenting as possible. Comments that point out the obvious, should be eliminated. Comments that make it easier to understand the intent, purpose, and use of a given method or section of code can be invaluable to those of us dolts that may be less familiar with the language or code in question. Structured comments that allow for the generation of API documentation are a good example. Just don't comment an IF statement that checks to see if a checkbox is checked and tell me that you're checking to see if the checkbox is checked. Restating the obvious in a comment is the worst waste keystrokes in our universe.

//For example, the above text deals with what is a useful comment

所谓的自文档代码的真正问题在于它传达了它实际做的事情。虽然一些注释可以帮助别人更好地理解代码(例如,算法步骤等),但它在一定程度上是多余的,我怀疑你能否说服你的同行。

然而,文档中真正重要的是代码中没有直接体现出来的东西:潜在的意图、假设、影响、限制等等。

能够通过快速浏览来确定代码执行X操作比能够确定代码不执行Y操作要容易得多。他必须记录Y…

你可以给他看一个代码的例子,看起来很好,很明显,但实际上并没有覆盖所有的输入基,比如,看看他是否能找到它。

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

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

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

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