阿里巴巴Java开发规约第一章-注释规约篇

1.[强制] 类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用// xxx方式。

说明: 在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释;在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

老四附言:

简单复习一下什么是Javadoc，他其实是一个命令，根据Java注释来为项目生成自己的api文档，所以我们编写代码的时候为自己设置一套标准的注释模版，有利于我们日后为自己的项目生成比较容易阅读的api文档。

2.[强制] 所有的抽象方法(包括接口中的方法)必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

说明: 对子类的实现要求，或者调用注意事项，请一并说明。

老四附言:

接口一般用于给其他人承接，所以解释越清晰越好。所以高要求严标准会使我们的代码更加容易阅读，项目的api文档也会更详细。

3.[强制] 所有的类都必须添加创建者和创建日期。

老四附言:

找锅的时候是相当有力的证据呢!

4.[强制] 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

老四附言:

老四现在已经养成了这样的习惯，后面也会分享出一个参考的eclipse的代码注释模版给大家，虽然不是很标准，但是在p3c的校验之下一般都是没问题的。文末可以自助下载。

5.[强制] 所有的枚举类型字段必须要有注释，说明每个数据项的用途。

老四附言:

关于枚举的基本知识用得少的人可能还不太熟悉，它也是Java1.5新增的一个小功能，但是却极大的方便了我们代码编写。比如以前要一行一行的写public static final这种静静态常量，枚举可以更简洁的来定义。老四在这里再简单阐述一下关于枚举的使用以及各个使用场景，让大家再简单的复习一下，代码中的所有注释都会经过p3c的校验。

我们都知道实例有限而且固定的类，被称为枚举类。jdk1.5之前基本上都是向下面这样定义静态常量表示枚举。

以上定义枚举的缺点:

• 类型不安全，比如将春夏秋冬定义成整型的1234，哪天来个傻逼就有可能用春夏秋冬给你做算术运算了。
• 没有命名空间，意思就是除非你自己定义命名空间，否则A.class中有一个SUCCESS=”1″，B.class中有一个SUCCESS=”ok”，就容易发生错乱。
• 打印输出的意义有的时候让人丈二的和尚摸不着头脑，比如输出SUMMER，却输出字符1，有的时候不看注释不知道这个1代表什么。

接下来我们看看枚举这个特殊类的基本知识:

枚举类使用关键字enum标识，java中一种特殊的类，既然是类，就不管他特不特殊，它一样可以拥有自己的成员变量、方法等，构造器，实现接口也是完全ojbk。那么枚举类特殊的地方在哪里?

• 可以实现多个接口，但是因为枚举类继承了java.lang.Enum类，所以不能显示继承其他父类。
• 不能派生子类，因为枚举默认使用final修饰，关于final的用法以及介绍可以参考一下老四的这篇文章《Java面向对象之final修饰符》。
• 枚举类的构造器能且只能用private关键字修饰。
• 第一行必须显示列出枚举类的所有实例。

一个简单的枚举类演示:

刚才提到，枚举类虽然作为特殊的Java类，但是一样也能定义成员变量、方法和构造器，并且枚举类通常要设置成不可变类，在枚举类中定义成员变量应该是常量，这样才能更安全，代码也会更简洁。当然这里面的写法和正常的构造实例有所不同，相信用过的都知道是怎么回事了吧。

一个带有成员变量(构造器使用)和构造的枚举类实例如下:

前面说过，Enum枚举类可以实现多个接口，和普通实现接口不同的是，如果枚举类的每个实例需要实现不同的行为的时候，可以让每个枚举值分别实现接口的方法，每个枚举值提供不同的实现方式，从而实现不同的枚举值有不同的对象行为。

实例如下:

除了以上，枚举类还可以实现抽象类，其实和接口很像，就是在枚举值的代码中实现抽象类的具体实现，但是切记不需要将枚举类用abstract关键字显示的将枚举类定义成抽象类，系统会自动添加。具体的例子就不掩饰了。

6.[推荐] 与其”半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

反例: “TCP连接超时”解释成”传输控制协议连接超时”，理解反而费脑筋。

老四附言:

还有一点，除了注释意外，如果英文词汇量不是很多很丰富，那么编程的时候和谷歌翻译配合使用更配哦。

7.[推荐] 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

说明: 代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。

老四附言:

所以说敲代码的时候不要偷懒不要着急，尽量的做到尽善尽美，造福后人。程序员千万别为难程序员。

8.[参考] 谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明: 代码被注释掉有两种可能性:

• 后续会恢复此段代码逻辑。
• 永久不用。

前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。

老四附言:

这句话很在理了，开发过程中，如果注释掉的这段代码再上线之前还需要使用或者调试，就不要先删除。但老四个人觉得如果要进行提交等代码持久化的操作是可以将无用代码删除的(同一level水平的切换代码还是要保留的，如: 测试/正式数据库环境配置)。

9.[参考] 对于注释的要求: 第一、能够准确反应设计思想和代码逻辑;第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路;注释也是给继任者看的，使其能够快速接替自己的工作。

老四附言:

说的不对吗?

10.[参考] 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端: 过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

反例:

方法名put，加上两个有意义的变量名elephant和fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。

老四附言:

兑兑兑，奖得兑。

11.[参考] 特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

• 待办事宜(TODO): (标记人，标记时间，[预计处理时间])，表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法(因为它是一个Javadoc标签)。
• 错误，不能工作(FIXME): (标记人，标记时间，[预计处理时间])，在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

老四附言:

eclipse版本的codetemplates.xml文件文末自助本小站即可下载，不要钱，随便下载。

更博不易，如果觉得文章对你有帮助并且有能力的老铁烦请赞助盒烟钱，点我去赞助。或者扫描文章下面的微信/支付宝二维码打赏任意金额，老四这里抱拳了。赞助时请备注姓名或者昵称，因为您的署名会出现在赞赏列表页面，您的赞赏钱财也会被用于小站的服务器运维上面，再次抱拳。