Java 语法规定之外的命名注释规范

命名规范

1. 项目名

项目名全部小写，且不使用下划线，含多个单词时使用中划线分隔。

2. 包名

包名全部小写，且不使用下划线，即便含多个单词也不分隔。对于不同的项目，包名分为以下几种：（此部分与域名类似，可参考域名规则）

• 公司项目：com.公司名.项目名.模块名.具体分类

• 非盈利组织：org.组织名.项目名.模块名.具体分类

• 团队项目：team.团队名.项目名.模块名.具体分类

• 其它：

  • 个人项目：表示个人的英语单词有 individual、personal、private、one-man 等

    • indi：个体项目。指个人发起，但非自己独自完成的项目，可公开或私有项目，版权主要属于发起者。

      包名规则：indi.发起者名.项目名.模块名.具体分类

    • pers：个人项目。指个人发起，独自完成，可分享的项目，版权主要属于个人。

      包名规则：pers.个人名.项目名.模块名.具体分类

    • priv：私有项目。指个人发起，独自完成，非公开的私人使用的项目，版权属于个人。

      包名规则：priv.个人名.项目名.模块名.具体分类

    • onem：与 indi 相同

3. 类名

类名首字母大写，如果类名由多个单词组成，每个单词的首字母都要大写。如：

   public class MainActivity extends AppCompatActivity { /* TODO */ }

另外，类名最好为名词，或者是以名词结尾，而前缀为修饰该名词的形容词、动名词。

4. 常量名

常量名全部大写。如果名称由多个单词组成，则这些单词之间使用下划线隔开。如：

   public static final int MAX_LENGTH = 100;

5. 变量名

变量名的首字母小写。如果名称由多个单词组成，则从第二个单词开始，每个单词的首字母都要大写。如：

   private boolean upPressed;

对于泛型形参，其遵循类名的规则。

另外，在定义泛型类型形参时，其习惯的象征意义为：

• E：表示集合的元素类型

• K、V：分别表示集合中键和值的类型

• T、U、S：均表示任意类型

6. 方法名

变量名的首字母小写。如果名称由多个单词组成，则从第二个单词开始，每个单词的首字母都要大写。 如：

   public void setName(String aName) { this.name = aName; }

对于不同领域的方法，其附加的规则为：

• Service / DAO 层方法命名规则：

  • 字段初始化的方法用 set 做前缀。

  • 插入的方法用 save 或 insert 做前缀。

  • 获取单个对象的方法用 get 做前缀。

  • 获取多个对象的方法用 list 做前缀。

  • 修改的方法用 update 做前缀。

  • 删除的方法用 remove 或 delete 做前缀。

  • 获取统计值的方法用 count 做前缀。

• 领域模型命名规则：

  • 数据对象： xxxDO。 其中xxx 为数据表名。

  • 数据传输对象： xxxDTO。 其中 xxx 为业务领域相关的名称。

  • 展示对象： xxxVO， xxx 为网页名称。

  注意： POJO 是 DO 、 DTO、 BO 、VO 的统称，所以不要命名成 xxxPOJO 。

8. 其它命名技巧

• 直接使用类型名命名。如：

      View view;
  

• 在变量名前面加上一些前缀。如：a

  附： 在 C++ 中，往往喜欢使用前缀 m，x，下划线_，Java 程序员通常不这么做

      Box aBox;
  

• 使用谐音简化。如使用数字2来替代单词to，使用数字4来替代单词for。

  在这种情况下，数字本身也能起到分隔字母的作用，因此这种技巧能替代使用大写字母进行分隔，但数字谐音不能充当后缀。

9. 应当避免的行为

• 使用单个英文小写字母作为名称。如：i，j，k，a

• 使用简单泛化意义的数字作为后缀。如：1、2、…

• 类方法形参变量的名称和类字段相同

• 使用英文以外的人类文字。如：使用中文、汉语拼音

10. 经典的命名法

• 下划线命名法：

  单词与单词之间通过下划线分隔。

• 驼峰式命名法（小驼峰式命名法）：

  第一个单词首字母小写，后面的单词首字母大写，其它字母均小写。

• 帕斯卡命名法（大驼峰式命名法）：

  每个单词的第一个字母都大写，其它字母均小写。

• 匈牙利命名法：

  开头字母用变量类型的缩写，这一部分全部用小写。其余部分用变量的英文或英文的缩写，这一部分的大小写遵循帕斯卡命名法。

11. 常用命名词汇

• 笔者常用的匈牙利缩写命名如下表：

  缩写	全称	意义
  ptr	pointer	指针
  src	source	来源
  rsp	response	响应
  impl	implement	实现
  -	-	-
  msg	message	信息
  img	image	图像
  -	-	-
  btn	button	按钮
  dlg	dialog	对话框
  -	-	-
  fx	framework	框架

• 笔者常用的前缀缩写如下表：

  缩写	全称	意义
  opt	option	选择
  info	information	信息
  req	request	请求

• 普通的匈牙利命名如下表：

  缩写	意义
  a	数组（Array）
  b	布尔值（Boolean）
  by	字节（BYte）
  c	有符号字符（Char）
  cb	无符号字符（Char Byte）
  cr	颜色参考值（Color Reference）
  cx、cy	坐标差（坐标：Coordinate）
  dw	双字节（Double Word）
  fn	函数（FuNction）
  h	句柄（Handle）
  i	整型（Int）
  l	长整型（Long int）
  lp	长指针（Long Pointer）
  m	类成员（class Member）
  n	短整型（Number）
  np	近程指针（Near Pointer）
  p	指针（Pointer）
  s	字符串（String）
  sz	以 null 结尾的字符串（String with Zero end）
  w	字（Word）

• 多用于包名或类名

  意义	拼写	位置
  抽象	Abstract、Base	前缀
  枚举	Enum	后缀
  接口实现	Impl	后缀
  异常	Exception	后缀
  工具	Utils	后缀
  测试	Test	后缀
  处理器 / 校验器	Handler / Validator	-
  断言	Predicate	-
  包装类	Wrapper	后缀

  意义（领域模型系列）	拼写（后缀）
  -	DO
  -	DTO
  -	VO
  -	DAO

  意义（设计模式系列）	拼写（后缀）
  -	Builder
  -	Factory

  意义（MVC系列）	拼写（后缀）
  控制器	Controller
  服务	Service
  数据访问对象	DAO

注释规范

1. 类注释

类注释在每个类的前面添加。注释模板如下：

   /**
   * Copyright (C), 2020-202X, Company name info. Co., Ltd.
   * FileName: Test.java
   * 类的详细说明
   *
   * @author 类创建者姓名
   * @Date  创建日期
   * @version 版本号
   */

2.字段注释

字段注释在每个字段的前面添加。注释模板如下：

   /** 这是为了保证软件开始界面的提示信息只提示一次 */
   private static int startMessageCounter = 0;

3.构造器注释

构造器注释在每个构造器方法的前面添加。注释模板如下：

   /**
   * 构造方法的详细使用说明
   *
   * @param 参数1 参数1的使用说明
   * @throws 异常类型.错误代码 注明从此类方法中抛出异常的说明
   */

4.方法注释

方法注释在每个方法的前面添加。注释模板如下：

   /**
   * 类方法的详细使用说明
   *
   * @param 参数1 参数1的使用说明
   * @return 返回结果的说明
   * @throws 异常类型.错误代码 注明从此类方法中抛出异常的说明
   */

5.方法内部注释

方法内部注释添加在所需要注释的代码前面，可使用一行或多行。如：

   // 创建Spring容器
   var ctx = new ClassPathXmlApplicationContext("spring-config.xml");