上一篇文章我们介绍了注释的种类，最后总结得出：代码无法表述的信息、目的性注释和概述性注释 这三种注释是我们比较提倡使用的注释分类，有助于提高代码的可阅读性，从而提高代码的维护性。今天我们要介绍的是如何高效的注释。
日常开发者，我们可能没有那么多时间去慢慢思考或者优化我们的注释，有些人甚至会抱怨说连编码的时间都不够，更何况还要添加注释。所以，我们推崇高效注释，注释太多并不比注释太少好，反之也一样，高效注释帮助你到达折中点。
如果注释占用你太多时间通过可能的原因有两点。第一，注释的风格可能耗时或者枯燥泛味。如果是这样的话，应该赶快改变注释风格。需要大量工作量的注释风格维护起来会令人头疼，如果注释不易修改，于是，就算代码变了，注释也没有更新，注释就变得不准确，起到误导作用，比没有注释更可怕。第二，说明的你的程序是干了什么的都不好说出来，所以写注释太难。这通常是你没有理解程序的信号，写注释的过程中也让你更好地理解程序，所以不管写不写注释，这些时间是值得花的。
高效注释
下面给出几条高效注释的原则。
采用不会打断或易于修改的注释风格
任何太具想象力的风格维护起来都会让你崩溃，例如下面这几个例子：
// Variable Meaning
// ------- -------
// xPos ........... XCoordinate Position (in meters)
// yPos ........... YCoordinate Position (in meters)
// ndsCmptng ...... Needs computing (= 0 if no computation is needed,
// = 1 if computation is needed)
维护哪些前导字符 ... 太麻烦了，它们看起来是挺好看，也没有碍事，但是修改代码的时候，会添加大量的工作。
再看一个例子：
/**********************************************************************************
* class: Gigatron (GIGATON.CPP) *
* *
* author: Dwight K. Coder *
* date: July 4, 2014 *
* *
* Routines to control the twenty-first century's code evaluation *
* tool. The entry point these routines is the EvaluateCode() *
**********************************************************************************/
这个例子看上去非常美观，它是一个整体，注释开始和结尾也很明显。但是修改这段注释的难易程度就不好说了，如果想要在注释最后加上一行，就得仔细调整 * ；如果要修改这段注释，左右两边的 * 都要小心地设置，所以维护这段注释工作量太大。如果你实在喜欢 *，将注释调整一下：
/**********************************************************************************
class: Gigatron (GIGATON.CPP)
author: Dwight K. Coder
date: July 4, 2014
Routines to control the twenty-first century's code evaluation
tool. The entry point these routines is the EvaluateCode()
**********************************************************************************/
这样也容易维护多了。
用伪代码编程法减少注释时间
写代码之前以注释先勾勒出代码，然后慢慢再完善代码，完成代码的时候，注释也一起顺便完成了，不用专门花时间写注释。在填充低层次具体的逻辑代码之前，先把高层次的伪代码完成，这也更加有助于你的程序设计。
将注释集成到你的开发风格中
跟将注释集成到你的开发风格背道而驰地是项目快结束的时候才开始写注释，这么做有很多缺点。写注释成了一种专门的任务，工作量看起来会比一点点积累的方式大。事后写注释比较耗时，因为你还得回忆或思考某行代码是干什么的，不能像编程的时候一样边写顺便把注释写下来。而且你可能很容易忘掉一些设计细节，导致你的注释不够准确。
可能有人觉得当花精力去写代码的时候，分心去写注释，会影响写代码的质量。如果你编程时集中精力这么难，以至于写注释就会打断思路，那你应该先写伪代码，再把伪代码转换成注释。
如果你的设计很难编程，在担忧注释或写代码之前应该着手去优化设计，或者先用伪代码理清自己的思路，编码就更容易了，注释自然而然也就完成了。
性能不是逃避注释的借口
在早期的一些 Basic 程序中，注释会使得程序跑得慢，还有90年的 ASP 也存在这样的问题，到了21世纪，Javascript 等需要通过网络连接来传输的代码也有类似的问题。
对于上述这些情况，最终的方案都不是不要注释，而是创建区分于开发版和发布版代码，通过一些专门对代码处理的工具，在发版之前把代码注释清除掉，这也是构建过程的一部分。
除了上述这些原则，我们还要探讨的一个问题是：最佳注释量 。
最佳注释量
IBM的研究发现，约每十条语句就有一个注释，这样的密度时程序清晰度最高。如果注释过多或者过少的密度让代码难易理解。
这个结论被滥用，有的项目会采取诸如“程序员必须每5行代码至少有一条注释”的标准，这种标准应付的只是程序代码不清的表象，而没有追溯它的根源。
如果你熟练使用伪代码编程法，你可以做到每隔几行就添加一个注释，但是注释数目不一定对代码起到正向的作用，反而给读者带来副作用。与其关心注释数目，比如花更多的精力检查每个注释有无作用，如果所有的注释说明了写代码的缘由，又符合高效注释的原则，这样的注释就足够了。
小结
本文介绍了高效注释的几条最佳实践：采用不会打断或易于修改的注释风格、用伪代码编程减少注释时间、将注释集成到你的开发风格当中、性能不是逃避注释的借口 ，让我们从注释风格、编程方式、开发风格等各种角度认识了进行高效注释的正确打开方式。最后通过IBM的例子告诉我们，不要盲目相信什么每隔几行代码就要添加一条注释的原则，只有在需要的时候再添加注释，否则注释就成为了我们阅读代码和开发人员的累赘。
最后
本文是笔者阅读了 《代码大全》 关于注释的章节写的读书笔记，文中观点是读者阅读书后加入自己的理解后提炼出来的，如有不足，望指出或给出更好的建议。这是关于注释的第三篇，下一篇文章我会围绕注释的技术介绍不同的场景下怎么样去添加合适的注释。想了解更多注释的知识，查看往期文章：
