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

悠悠 2021-09-25 00:54 425阅读 0赞

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

*  命名规范
 *   *  1. 项目名
     *  2. 包名
     *  3. 类名
     *  4. 常量名
     *  5. 变量名
     *  6. 方法名
     *  8. 其它命名技巧
     *  9. 应当避免的行为
     *  10. 经典的命名法
 *  注释规范
 *   *  1. 类注释
     *  2.字段注释
     *  3.构造器注释
     *  4.方法注释
     *  5.方法内部注释

# 命名规范 #

## 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 */ }

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

*  惯用词汇如下：
    
    <table> 
     <thead> 
      <tr> 
       <th align="center">意义</th> 
       <th align="center">拼写</th> 
       <th align="center">位置</th> 
      </tr> 
     </thead> 
     <tbody> 
      <tr> 
       <td align="center">抽象</td> 
       <td align="center">Abstract、Base</td> 
       <td align="center">前缀</td> 
      </tr> 
      <tr> 
       <td align="center">枚举</td> 
       <td align="center">Enum</td> 
       <td align="center">后缀</td> 
      </tr> 
      <tr> 
       <td align="center">接口实现</td> 
       <td align="center">Impl</td> 
       <td align="center">后缀</td> 
      </tr> 
      <tr> 
       <td align="center">异常</td> 
       <td align="center">Exception</td> 
       <td align="center">后缀</td> 
      </tr> 
      <tr> 
       <td align="center">工具</td> 
       <td align="center">Utils</td> 
       <td align="center">后缀</td> 
      </tr> 
      <tr> 
       <td align="center">测试</td> 
       <td align="center">Test</td> 
       <td align="center">后缀</td> 
      </tr> 
      <tr> 
       <td align="center">处理器 / 校验器</td> 
       <td align="center">Handler / Validator</td> 
       <td align="center">-</td> 
      </tr> 
      <tr> 
       <td align="center">断言</td> 
       <td align="center">Predicate</td> 
       <td align="center">-</td> 
      </tr> 
     </tbody> 
    </table>
    
    <table> 
     <thead> 
      <tr> 
       <th align="center">意义（领域模型系列）</th> 
       <th align="center">拼写（后缀）</th> 
      </tr> 
     </thead> 
     <tbody> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">DO</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">DTO</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">VO</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">DAO</td> 
      </tr> 
     </tbody> 
    </table>
    
    <table> 
     <thead> 
      <tr> 
       <th align="center">意义（设计模式系列）</th> 
       <th align="center">拼写（后缀）</th> 
      </tr> 
     </thead> 
     <tbody> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">Builder</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">Factory</td> 
      </tr> 
     </tbody> 
    </table>
    
    <table> 
     <thead> 
      <tr> 
       <th align="center">意义（MVC系列）</th> 
       <th align="center">拼写（后缀）</th> 
      </tr> 
     </thead> 
     <tbody> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">Controller</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">Service</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">Servicelmpl</td> 
      </tr> 
      <tr> 
       <td align="center">-</td> 
       <td align="center">DAO</td> 
      </tr> 
     </tbody> 
    </table>

## 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. 经典的命名法 ##

*  下划线命名法：
    
    单词与单词之间通过下划线分隔。
 *  驼峰式命名法（小驼峰式命名法）：
    
    第一个单词首字母小写，后面的单词首字母大写，其它字母均小写。
 *  帕斯卡命名法（大驼峰式命名法）：
    
    每个单词的第一个字母都大写，其它字母均小写。
 *  匈牙利命名法：
    
    开头字母用变量类型的缩写，这一部分全部用小写。其余部分用变量的英文或英文的缩写，这一部分的大小写遵循帕斯卡命名法。
    
     *  笔者常用的匈牙利缩写命名如下表：
        
        <table> 
         <thead> 
          <tr> 
           <th align="center">缩写</th> 
           <th align="center">全称</th> 
           <th align="center">意义</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td align="center">ptr</td> 
           <td align="center">pointer</td> 
           <td align="center">指针</td> 
          </tr> 
          <tr> 
           <td align="center">src</td> 
           <td align="center">source</td> 
           <td align="center">来源</td> 
          </tr> 
          <tr> 
           <td align="center">rsp</td> 
           <td align="center">response</td> 
           <td align="center">响应</td> 
          </tr> 
          <tr> 
           <td align="center">impl</td> 
           <td align="center">implement</td> 
           <td align="center">实现</td> 
          </tr> 
          <tr> 
           <td align="center">-</td> 
           <td align="center">-</td> 
           <td align="center">-</td> 
          </tr> 
          <tr> 
           <td align="center">msg</td> 
           <td align="center">message</td> 
           <td align="center">信息</td> 
          </tr> 
          <tr> 
           <td align="center">img</td> 
           <td align="center">image</td> 
           <td align="center">图像</td> 
          </tr> 
          <tr> 
           <td align="center">-</td> 
           <td align="center">-</td> 
           <td align="center">-</td> 
          </tr> 
          <tr> 
           <td align="center">btn</td> 
           <td align="center">button</td> 
           <td align="center">按钮</td> 
          </tr> 
          <tr> 
           <td align="center">dlg</td> 
           <td align="center">dialog</td> 
           <td align="center">对话框</td> 
          </tr> 
          <tr> 
           <td align="center">-</td> 
           <td align="center">-</td> 
           <td align="center">-</td> 
          </tr> 
          <tr> 
           <td align="center">fx</td> 
           <td align="center">framework</td> 
           <td align="center">框架</td> 
          </tr> 
         </tbody> 
        </table>
     *  笔者常用的前缀缩写如下表：
        
        <table> 
         <thead> 
          <tr> 
           <th align="center">缩写</th> 
           <th align="center">全称</th> 
           <th align="center">意义</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td align="center">opt</td> 
           <td align="center">option</td> 
           <td align="center">选择</td> 
          </tr> 
          <tr> 
           <td align="center">info</td> 
           <td align="center">information</td> 
           <td align="center">信息</td> 
          </tr> 
          <tr> 
           <td align="center">req</td> 
           <td align="center">request</td> 
           <td align="center">请求</td> 
          </tr> 
         </tbody> 
        </table>
     *  普通的匈牙利命名如下表：
        
        <table> 
         <thead> 
          <tr> 
           <th align="center">缩写</th> 
           <th align="center">意义</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td align="center">a</td> 
           <td align="center">数组（Array）</td> 
          </tr> 
          <tr> 
           <td align="center">b</td> 
           <td align="center">布尔值（Boolean）</td> 
          </tr> 
          <tr> 
           <td align="center">by</td> 
           <td align="center">字节（BYte）</td> 
          </tr> 
          <tr> 
           <td align="center">c</td> 
           <td align="center">有符号字符（Char）</td> 
          </tr> 
          <tr> 
           <td align="center">cb</td> 
           <td align="center">无符号字符（Char Byte）</td> 
          </tr> 
          <tr> 
           <td align="center">cr</td> 
           <td align="center">颜色参考值（Color Reference）</td> 
          </tr> 
          <tr> 
           <td align="center">cx、cy</td> 
           <td align="center">坐标差（坐标：Coordinate）</td> 
          </tr> 
          <tr> 
           <td align="center">dw</td> 
           <td align="center">双字节（Double Word）</td> 
          </tr> 
          <tr> 
           <td align="center">fn</td> 
           <td align="center">函数（FuNction）</td> 
          </tr> 
          <tr> 
           <td align="center">h</td> 
           <td align="center">句柄（Handle）</td> 
          </tr> 
          <tr> 
           <td align="center">i</td> 
           <td align="center">整型（Int）</td> 
          </tr> 
          <tr> 
           <td align="center">l</td> 
           <td align="center">长整型（Long int）</td> 
          </tr> 
          <tr> 
           <td align="center">lp</td> 
           <td align="center">长指针（Long Pointer）</td> 
          </tr> 
          <tr> 
           <td align="center">m</td> 
           <td align="center">类成员（class Member）</td> 
          </tr> 
          <tr> 
           <td align="center">n</td> 
           <td align="center">短整型（Number）</td> 
          </tr> 
          <tr> 
           <td align="center">np</td> 
           <td align="center">近程指针（Near Pointer）</td> 
          </tr> 
          <tr> 
           <td align="center">p</td> 
           <td align="center">指针（Pointer）</td> 
          </tr> 
          <tr> 
           <td align="center">s</td> 
           <td align="center">字符串（String）</td> 
          </tr> 
          <tr> 
           <td align="center">sz</td> 
           <td align="center">以 null 结尾的字符串（String with Zero end）</td> 
          </tr> 
          <tr> 
           <td align="center">w</td> 
           <td align="center">字（Word）</td> 
          </tr> 
         </tbody> 
        </table>

# 注释规范 #

## 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.方法注释 ##

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