Java编码命名规范

俗话说：“没有规矩不成方圆”。编程工作往往都是一个团队协同进行，因而一致的编码规范非常有必要，这样写成的代码便于团队中的其他人员阅读，也便于编写者自己以后阅读。

命名规范

程序代码中到处都是标识符，因此取一个一致并且符合规范的名字非常重要。命名方法很多，但是比较有名的且被广泛接受的命

名法包括下面两种。

匈牙利命名，一般只是命名变量，原则是：变量名 = 类型前缀 + 描述，如bFoo表示布尔类型变量，pFoo表示指针类型变量。匈牙利命名还是有一定争议的，在Java编码规范中基本不被采用。

驼峰命名（Camel-Case），又称“骆驼命名法”，是指混合使用大小写字母来命名。驼峰命名又分为小驼峰法和大驼峰法。小驼峰法就是第一个单词是全部小写，后面的单词首字母大写，如myRoomCount；大驼峰法是第一个单词的首字母也大写，如ClassRoom。

除了包和常量外，Java编码规范命名方法采用驼峰法，下面分类说明一下。

**包名：**包名是全小写字母，中间可以由点分隔开。作为命名空间，包名应该具有唯一性，推荐采用公司或组织域名的倒置，如

com.apple.quicktime.v2。但Java核心库包名不采用域名的倒置命名，如java.awt.event。

**类和接口名：**采用大驼峰法，如SplitViewController。

**文件名：**采用大驼峰法，如BlockOperation.java。

**变量：**采用小驼峰法，如studentNumber。

**常量名：**全大写，如果是由多个单词构成，可以用下划线隔开，如YEAR和WEEK_OF_MONTH。

**方法名：**采用小驼峰法，如balanceAccount、isButtonPressed等。

示例

package com.shouyerenst;
public class Date extends java.util.Date {
private static final int DEFAULT_CAPACITY = 10;
private int size;
public static Date valueOf(String s) {
final int YEAR_LENGTH = 4;
final int MONTH_LENGTH = 2;
int firstDash; int secondDash;
   }
public String toString () {
int year = super.getYear() + 1900;
int month = super.getMonth() + 1;
int day = super.getDate();
   }
}

注释规范

Java中注释的语法有三种：单行注释”//“、多行注释”/…/“和文档注释”/**…*/”。

文件注释

文件注释就是在每一个文件开头添加注释。文件注释通常包括如下信息：版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。

示例：

/** 版权所有 2022 shouyerenst 
* 许可信息查看LICENSE.txt文件
* 描述:
* 实现日期基本功能
* 历史版本:
* 2015-7-22:创建 守夜人st
* 2015-8-20: 添加socket库
* 2015-8-22: 添加math库
*/

上述注释只是提供了版权信息、文件内容和历史版本信息等，文件注释要根据本身的实际情况包括内容。

文档注释

文档注释就是指这种注释内容能够生成API帮助文档，JDK中javadoc命令能够提取这些注释信息并生成HTML文件。文档注释主要对类（或接口）、实例变量、静态变量、实例方法和静态方法等进行注释。

提示文档是要给别人看的帮助文档，一般注释的实例变量、静态变量、实例方法和静态方法都应该是非私有的，那些只给自己看的内容可以不用文档注释。

示例：

package com.shouterenst;
/**
* 自定义的日期类，具有日期基本功能，继承java.util.Date
* <p>实现日期对象和字符串之间的转换</p>
* @author 守夜人st
*/
public class Date extends java.util.Date { private static final int DEFAULT_CAPACITY = 10;
/**
* 容量
*/
public int size;
/**
* 将字符串转换为Date日期对象
* @param s 要转换的字符串
* @return Date日期对象
*/ 
public static Date valueOf(String s) {
final int YEAR_LENGTH = 4;
final int MONTH_LENGTH = 2;
int firstDash; int secondDash;
    }
/**
* 将日期转换为yyyy-mm-dd格式的字符串
* @return yyyy-mm-dd格式的字符串
*/ 
public String toString () {
int year = super.getYear() + 1900;
int month = super.getMonth() + 1;
int day = super.getDate();
    }
}

由于文档注释最终会生成HTML文档，所以可以在文档注释中使用HTML标签，上述注释中的

是HTML段落标签。另外，上述的文档注释中还用到了@author、@return和@param等文档注释标签，这些标签能够方便生成API帮助文档，下表所示是常用的文档注释标签。

标签	描述
@author	说明类或接口的作者
@deprecated	说明类、接口或成员已放弃
@param	说明方法参数
@return	说明返回值
@see	参考另一个主题的链接
@exception	说明方法所抛出的异常类
@throws	同@exception标签
@version	类或接口的版本

API帮助文档可参阅（选择对应JDK版本）https://docs.oracle.com/en/java/javase/11/docs/api/index.html

代码注释

程序代码中处理文档注释还需要在一些关键的地方添加代码注释，文档注释一般是给一些看不到源代码的人看的帮助文档，而代码注释是给阅读源代码的人参考的。代码注释一般是采用单行注释“//”和多行注释”/…/”。

示例：

public class Date extends java.util.Date {
    // 默认的容量，是一个常量 ①
    private static final int DEFAULT_CAPACITY = 10;
    /**
    * 容量
    */ 
    public int size;
    /**
    * 将字符串转换为Date日期对象
    * @param s 要转换的字符串
    * @return Date日期对象
    */
    public static Date valueOf(String s) {
        final int YEAR_LENGTH = 4;
        final int MONTH_LENGTH = 2;
        int firstDash; int secondDash;
        Date d = null;
    /* ② 
    * 判断d是否为空， 
    * 如果为空抛出异常IllegalArgumentException，否则返回d。
    */
        if (d == null) {
            throw new java.lang.IllegalArgumentException();
        }
        return d;
        }
    /**
    * 将日期转换为yyyy-mm-dd格式的字符串
    * @return yyyy-mm-dd格式的字符串
    */ 
    public String toString () {
        int year = super.getYear() + 1900; 
        //计算年份 ③ int month = super.getMonth() + 1;
        /*计算月份*/ ④ 
        int day = super.getDate();
        } 
}