原文自国外技术社区dzone,作者为 Brian Hannaway,传送门

我一直是一个崇拜注释的人,对我来说,这不是一个脑筋活,而是一件有意义的事情,并且对于为了更好地构建易懂易维护的软件中是尤其基础的一部分。虽然并不是每个人都认同这个观点,有部分人说,注释并不是必要的而且对于并不是非常重要的代码来说注释就像多此一举。在这篇文章中,我会尝试去怼这些言论并且告诉读者你们为什么我会认为有质量的注释是可维护软件中的重要组成。

帮助别人看懂你的代码

作为一名开发者,我们会花费相当长的一段时间去阅读和尝试去了解别人的代码。有时候这会演变成一件艰巨的任务。我们的大多数人都遇到过同样的窘境, 在零文档的"前人坑"代码中费劲心思 — 没有任何单元测试、没有任何注释。写着玩意儿的老哥可能已经不在了,并且留到我们这边去思考这"该死的"玩意应该怎么处理。可想而知,这一点也不有趣,难道不是吗?

这份经验应当提醒我们,作为一名开发者我们有责任去做实现功能外的事情并且尽量将代码写得易读,易理解和易维护。一个易读的代码库,对未来的开发以及以后接手你的任务的人来说都很有帮助。它可以让不同技术水平及不同技术领域的开发者都能理解你的代码并且减轻他们的工作负担从而提高开发效率。

注释 — 仅仅是拼图中的一部分

想要完成一副完整的拼图,来拼凑一个可维护的系统是需要数个重要的拼块的。基于我的个人经验,我罗列出一下几项。

你也许会惊讶为什么注释在这几点的最后。但这不影响注释的重要性,而这更能体现出它跟其他点的不同。开发者应该始终强调去编写易读的、具有良好结构的代码。注释就像锦上添花,为阅读源码的人提供那些在代码中不能表达的思想。

##想想那些看你代码的人

在系统的整个生命周期,具有不同层级技术、经验和领域知识的开发者会一起工作来开发代码。在一个方面,你们可能拥有非常有经验的技术领头人或者架构师;而在另一方面,你们可能也有刚从大学毕业的开发人员。但关键是,你永远不会知道将来是谁或者什么级别的人去对接你的代码。基于这一点,你应该编写你的注释让对尽可能多的人都管用。如果你是一个具有丰富领域知识的技术主管,那么你不应该把注释写得以为之后的人懂得和你一样多。相反,在写的过程中始终需要谨记他们都可能是经验不足的人。

你可能会认为,尤其对于有经验的开发者来说,编写注释的风险太明显了。虽然这确实是个风险,但更重要的是,当我们将一个注释视作显而易见的时候,其实我们是在一个主观的状态下。对于具有15年工作经验的技术领头人来说,一些明显的东西对于初级工程师可能就是非常难懂了。

是什么以及为什么

当其他开发者在查看你们的代码的时候,这里有两件事情你是想让他们了解的。那就是这些代码是做什么的为什么要这样做。让我们仔细看一看。

解释是什么的注释

编写良好的代码在许多情况下是用来做自我记录。你的目标应该是使你的代码变得更让人印象深刻,从而减少那些用来描述你的代码做什么的注释。然而,有时候这种描述性质的注解也是非常有用的。

解释为什么的注解

解释为什么用这些代码的注释也是非常重要的因为这个信息无法从代码中获得。以下是一些重要的例子来描述你选择这样做的原因

通俗的注释

我尽量使我的注释变得非正式和通俗的。想象下你的一个团队队员坐在你旁边并且你在解释你部分的代码是如何工作的。你可以用简单的术语来解释,让你的队员能够尽可能地理解。我认为注释也应该以相同的方式,通过简单的表达来回答问题。请记住,注释能够提供那些代码不能提供的信息,所以尽量使它们变得能够让别人接收的形式。

质量胜于数量

像生活中大大部分例子,注释应该强调质量而非数量。应该仔细、细心地使用注释,告诉读者一些代码无法轻易表达的内容。可以说,带有大量有用的注释的结构化、易读的代码,比起用大量注释来解释每行代码作用的糟糕的代码要好的多得多。

避免多余的注释,能够更清晰的描述代码的作用。注释和代码一样,需要不断去维护。避免多余的注解能够具减少维护开销,并且能够帮助读者关注那些重要的注解。

避免注释腐朽

注释腐朽是指当代码更新的时候但附带的注释没更新。这会导致注释过时并且与他们对应的代码是相矛盾的。注释腐朽经常被认为是代码注释的一个重要的缺点,但我认为这个观点有效性很低。虽然我同意注释腐朽是一件不好的事并且有些事情是需要避免的,但是这并不是一个完美的理由去停止对你的代码进行注释。最好的防止注释腐朽的方法是显而易见的。。。当更新代码的时候更新你的注释。和大多数好的实践一样,这需要以代码审核的形式,结合开发人员的纪律性来治理。

包装起来

注释并不能代替结构良好、易读的代码,但是它们能通过表达那些代码不能表达的信息来帮助开发者们。更容易阅读、理解和维护的代码最终转化成更高的生产力和更多的模块被创造出来。我敢打赌这也能够使你的 boss 感到愉悦吧。