程序中注释的种类及替代方案

在 [url=http://kidneyball.iteye.com/blog/1733705]To 注释 or not 注释， that is a question[/url] 中，我认为程序中的内部注释——如果百分百准确地话——虽然在一定程度上对阅读程序有帮助，但在变化的项目中，却引入了注释自身的维护问题。而[color=red][b]注释如果缺乏维护，最终将形成失效或者误导性的干扰信息，反而对妨碍了程序的正常维护。[/b][/color]而注释的维护，是很难开展的，既缺乏有效的管理和技术手段，又缺乏明确的责任界定。因此建议是：[color=red][b]写程序的人，尽量少写内部注释。读程序的人，尽量少依赖内部注释。[/b][/color]那么，问题来了，在当今的技术环境中，有没有可以替代注释的技术方案，既能使程序容易阅读，又没有内部注释的种种问题？
 
 好消息是，不但有，而且都是已经在开发行业中使用了多年的成熟的方案。坏消息是，如果没有使用它们的习惯，在刚开始时不如随意写个注释顺手。所以问题只是我们肯不肯用。首先面临的问题就是，针对不同的注释，替代方案是不同的，我们需要针对不同的情况来选择。那么下面就来谈一谈内部注释的不同种类，以及它们的替代方案。
 
 在开始之前，先强调一下：
 
 1. 全文都是个人观点，就不在每一句之前都加上“个人认为”了；
 
 2. 这些替代方案均需要开发工具支持，例如IDE，版本控制工具等等。本文主要针对在协作环境中开发业务系统的一般情况。在远程终端里用vim写程序的朋友请完全跳过本文。
 
 3. 如非特别说明，文中“注释”表示程序的内部注释，[b][u]不包括在公共方法或类上以注释形式编写，实质是联机文档的文字[/u][/b]，例如JavaDoc；
 
 4. 在内部注释中，对没有任何代码与之对应的注释（比如说，TODO和FIXME）不在讨论范围内。详情请参看前文，我认为这些注释的维护难度与危害性都不如说明具体代码的注释严重，而且尚没有好的替代方案，在这些情况下应该继续使用注释；
 
 5. 下文介绍的替代方案和工具的选择都只是我自己常用的，不排除有更好的。就当抛砖引玉吧。
 
 好，下面开始。
 
 [size=xx-large][b]第一种注释：提示性的行内注释[/b][/size]
 
 这种注释产生的原因是，在编写或阅读程序时，程序员感觉到在大段代码中有一个代码片段不好理解，于是在这段代码之前或行末加入注释说明。这类注释通常是针对这段代码稍微高层含义的简短说明。比如说，在一段双重循环前面注释：“冒泡排序”或者“按照员工年龄排序”等等
 
 这种注释最大好处是，在排查错误时它能帮助程序员跳过大段的无关片段，但一旦失效，危害也很大。比如说“按照员工年龄排序”的循环片段，有可能其实是“按照员工工龄排序”（错别字），也很难避免在后续维护中有人顺便在这个循环里干点什么其他事情，而又没有修改注释。从而导致你跳过了发现问题的关键位置。相对来说，这种注释对阅读代码的负面影响就不太大，它的好处在于能帮助我们快速了解一段代码的设计意图，在阅读时不会太迷惘，即使失效了，因为最终还是要阅读代码，所以除了浪费时间，一般不会有大的问题。
 
 顺便扯一下，对于一个新手，这种注释确实对理解代码有帮助。但最好不要忘记，从代码直接推导设计意图也是程序员的基本功之一。如果你发现离开了注释就对一些复杂的代码完全无从入手，或者容易犯困或头痛，那最好先把这种基本功锻炼起来再借助注释提高速度。有一个事实是无法改变的：无论你拿到的代码有没有注释，活总是要干的，而你总有一天会遇到没有注释的代码。如果你根本不能完成的事情，而别人努力一把就能完成，即使你把那个写程序不写注释的人上下三代都骂遍，你也无法改变在经理眼中你的能力就是比别人差的印象。
 
 言归正传，在实践中如何消除这种注释呢，主要手段就是[color=red][b]用命名代替注释[/b][/color]。对于变量或常量，与其随便起个名字，然后用注释来说明它是干什么的，不如直接让它的名称说明自己是什么（英文不好？这个下面会谈）。
 
 至于复杂的表达式和程序片段，既然你能一段提示性的注释说明它的功能，这说明它是一个