Java 基础--编码规范

Java 编码规范

命名规范

• 命名方法

  • 匈牙利命名
    • 一般值命名变量
    • 原则：变量名=类型前缀+描述
    • 例如：bFoo（布尔型变量）、pFoo（指针类型变量）
  • 驼峰命名（最常用）
    • 混合使用大小写字母命名
    • 小驼峰法：第一个单词小写，其他单词首字母大写，例如：myRoomCount
    • 大驼峰法：单词首字母都大写，例如：ClassRoom

• 包名：全小写，中间可以用点（.）分隔开，

  • 作为命名空间，报名应具有唯一性，可以采用公司或组织域名倒置
  • java 核心库报名不采用域名倒置，例如：java.awt.event

• 类和接口名：采用大驼峰法

• 文件名：大驼峰法

• 变量：小驼峰法

• 常量名：全大写，由多个单词组成的用下划线（_）分隔开，例如：YEAR、WEEK_OF_MONTH

• 方法名：小驼峰法

注释规范

• 单行注释（//）
• 多行注释（/* … */）
• 文档注释（/** … */）

文件注释

在每一个文件开头添加注释

通常包含版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容、作用
例如

/*
*版权所有....
*许可证信息....
*描述：
*  ....
*历史版本：
*  ....
*/

文档注释

能生成 API 帮助文档

JDK 中 javadoc 命令能提取这些注释信息并生成 HTML 文件

文档注释主要对类（或接口）、实例变量、静态变量、实例方法、静态方法进行注释

• 文档注释标签

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

• 生成 API 帮助文档，可以使用 javadoc 命令

代码注释

• 单行：//
• 多行：/* … */

地标注释

• // TODO：此处由待处理任务，或未完成的代码
• // FIXME：此处代码是错误的，需要修正
• // XXX：此处代码已经完成，但是实现的方法还有待商讨

排版

空行

• 类声明和接口之间保留两个空行
• 两个方法之间保留一个空行
• 方法的第一条语句之前保留一个空行
• 代码注释（尾端注释除外）之前保留一个空行
• 一个方法内的两个逻辑段之间保留一个空行

空格

• 赋值符号（=）前后各一个空格

  • 例如

    a = b;
    

• 所有二元运算符有应该使用空格与操作数分开

  • 例如

    a = b + c;
    

• 一元操作符（负号、自增、自减等）与操作数之间没有空格

  • 例如

    a++;
    --b;
    

• 左小括号（“ ( ”）之后，右小括号（“ ) ”）之前不能有空格

• 左大括号（“ { ”）之前应有一个空格

  • 例如

    public static void main(String[] args) {
    
    }
    

• 方法参数列表左小括号（“ ( ”）之前没有空格，右小括号（“ ) ”）之后有一个空格

  • 例如

    public static void test(int a) {
    
    }
    

• 关键字之后紧跟着左小括号（“ ( ”），关键字之后应该有一个空格

  • 例如

    while (1) {
    
    }
    

缩进

• 通常将4个空格作为缩进排版的一个单位

• 一般默认一个制表符（Tab）等于8个空格

• 不同 IDE 工具制表符与空格对应个数可能不同，IDEA 中默认一个制表符对应4个空格

• 方法、Lambda、控制语句等包含大括号 “ {} ” 的代码块中，代码块的内容相对于首行缩进一个制表符（Tab）

  • 例如

    public class Date {
    	public void time() {
    		int year = super.getYear() + 1900;
    	}
    }
    

• if 语句中条件表达式的断行，新的一行应相对于上一行缩进两个指标都（Tab），再往后的断行应与第一次断行对齐

  • 例如

    if ((a == b)
    		|| (c > d) && (e != f)
    		&& (g <= h)) {
    		
    }
    

断行

• 一行代码最好不要超过80个字符
• 断行规范
  • 在一个逗号后断开
  • 在一个操作符前断开，要选择较高级别的运算符
  • 新的一行应相对于上一行索引两个制表符

其他规范

• 声明变量的时候最好一行声明一个

• 左大括号（“ { ”）位于声明语句同行的末尾，右大括号（“ } ”）另起一行，与相对应声明语句对齐；除非是一个空语句右大括号（“ } ”）应紧跟左大括号（“ { ”）之后

  • 例如

    public static void main(String[] args) {
    	while (1) {
    		
    	}
    }
    
    public static void setString() {}
    

• 每行最多包含一条语句

  • 例如

    a++;
    b--;
    
    // 不推荐
    a++; b--;
    

• if、for 等控制语句在只有一行代码的情况下最好不要省略两个大括号