我有一个同事,他坚持认为他的代码不需要注释,这是“自文档”。
我已经审阅了他的代码,虽然它比我看到的其他人编写的代码更清晰,但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码
它真的能取代注释良好和文档化的代码吗
在某些情况下,它是否比有良好文档和注释的代码更好
是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性,但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点,但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点,才能说服他。如果你有必要,可以提出一个新的问题,但不要在这里争论。
另外,那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
我很惊讶居然没有人提出“识字编程”,这是一种由德克萨斯州的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.)你应该读一读。
这是自文档化的代码,包括推理等。即使是一份很好的文件,
其他一切都是写得很好的评论:-)
自文档代码是一个很容易解决的问题,随着时间的推移,代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。
对我来说,以下是我努力遵循的规则:
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.
这意味着所有三种记录代码的方法都很接近,因此更有可能在代码更改时被更改,但它们所表达的内容并不重叠。
自文档代码是非常清晰的代码,以至于不需要注释。我举个小例子:
//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
}
如果没有注释,最后一个片段将很难破译。你可以想象其他更做作的例子。