只有在代码表达不清时才注释

原文链接

理论与实践的不同在于实践要比理论站的更高——这一观点也适用于注释。理论上,给代码注释是很有价值的观点:便于读者掌握细节,解释将会发生什么。什么比帮助更有帮助?然而在实践中,注释通常会成为一种障碍。和其他写作形式一样,写好注释是一种能力,知道什么时候不写注释是更重要的能力。

当代码格式错误时,编译器、解释器和其他工具肯定会提出反对。假如一段代码是功能性的错误,审查、静态分析、测试、日复一日的生产环境中大量的bug将浮现出来。但注释做呢?在《The Elements of Programming Style Kernighan and Plauger》指出如果出错了,注释的价值为零(或负的)。然而一些注释经常“乱丢”在代码库中,并以永远不可能出错的方式存在着。它们成为错误和分心的持续来源,对程序员的思维造成一种微妙的拖累。

哪些注释没有技术上的错误,但对代码没有任何价值?一些注释就是噪音。鹦鹉学舌般重复代码流程对读者而言没有额外的意义——用代码和自然语言各表达一次的情况并不会让其更正确或更实际。注释掉的代码是不可执行的,所以它对读者和运行时而言没什么帮助。它很快会变得陈旧。版本相关的注释及注释掉的代码都试图解决版本控制和历史问题。但这些问题已通过版本控制工具解决(效果更好)。

一些代码库中的噪声和错误注释会导致程序员忽略掉所有的注释,或通过跳过、或通过主动隐藏的方式。程序员有足够的智慧绕过任何被破坏掉的东西:折叠注释;选择一个和背景色差不多的配色方案给注释;写一个注释过滤脚本。为了避免代码库中由于程序员的创造导致的失误,以及减少真正有价值的注释被忽略掉的风险,应该像对待代码一样去对待注释。每一次注释都应该给读者带来附加值,其他存粹占空间的部分就应该被删掉或者重写。

什么叫作有价值?注释应该说的事情代码不要也不能说。一段代码的注释应该说明数据结构和编程约定,其他的地方代码会‘自圆其说’。而不是糟糕的方法或类名,重命名他们。不用写一大段长函数的注释,儿时提取其中匿名函数(较小部分),并写清楚其意图。尽可能尝试通过代码来表达。你想表达的和你代码本身表达的差异都会成为有用的候选注释。注释意味着代码自己不能说的,而不仅仅是代码没有说的。

0%