我有一个同事,他坚持认为他的代码不需要注释,这是“自文档”。
我已经审阅了他的代码,虽然它比我看到的其他人编写的代码更清晰,但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码
它真的能取代注释良好和文档化的代码吗
在某些情况下,它是否比有良好文档和注释的代码更好
是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性,但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点,但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点,才能说服他。如果你有必要,可以提出一个新的问题,但不要在这里争论。
另外,那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
不管纯粹的自文档代码是否可以实现,有一些事情是人们应该做的:
Never have code that is "surprising". Ie. don't use silly macro's to redefine things etc. Don't misuse operator overloading, don't try to be smart on this.
Split away code at the right point. Use proper abstractions. Instead of inlining a rolling buffer (a buffer with fixed length, with two pointers that gets items added at one end and removed at the other), use an abstraction with a proper name.
Keep function complexity low. If it gets too long or complex, try to split it out into other other functions.
当实现特定的复杂算法时,添加描述算法的文档(或链接)。但在这种情况下,要努力去除不必要的复杂性,增加易读性,因为很容易犯错误。
我很惊讶居然没有人提出“识字编程”,这是一种由德克萨斯州的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.)你应该读一读。
这是自文档化的代码,包括推理等。即使是一份很好的文件,
其他一切都是写得很好的评论:-)
我认为,质疑某一行代码是否具有自文档性是有意义的,但最终,如果你不理解一段代码的结构和功能,那么大多数时候注释是没有用的。以amdfan的“正确注释”代码片段为例:
/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
这段代码很好,但下面的代码在大多数现代软件系统中同样具有丰富的信息,并且明确认识到使用牛顿计算是一种选择,如果其他一些物理范式更合适,可能会被改变:
const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);
根据我个人的经验,很少有绝对需要注释的“正常”编码情况。举个例子,你有多频繁地使用自己的算法?基本上,其他一切都是构建系统的问题,以便编码器能够理解正在使用的结构以及驱动系统使用这些特定结构的选择。