Java基础学习总结（92）——Java编码规范之排版、注释及命名

为使开发人员养成良好的开发习惯，编写可读性强、易维护的程序，结合以往资料，现整理Java编码规范，将之做为开发人员的参照依据。

1、排版

一、相对独立的程序块之间必须加空行

下列状况应该使用一个空行：

• 两个方法之间

• 方法内的局部变量和方法的第一条语句之间

• 块注释或单行注释以前

• 一个方法内的两个逻辑段之间

二、单行长度不超过120个字符，如超出则换行，且操做符应放在行首，新行要有相对缩进

三、多个参数之间，二元运算符左右，for语句表达式之间应用空格隔开

表达式之间用空格隔开

四、多个短语句不要写在一行中，也就是说一行只写一条语句

五、while、for、if、do、case、default、switch等语句独占一行，且while、for、do、if等语句的执行部分不管有多少句，都要用“{}”括起来

六、程序首行缩进4个空格数，不容许使用TAB缩进（使用空格可很好的适应不一样操做系统的开发工具）

2、注释

注释应遵循的原则：

• 注释的内容要清楚、明了，含义准确，防止注释二义性。同时应尽可能避免在注释中使用缩写，特别是不经常使用缩写。如须要写，则进行必要的说明。

• 源程序有效注释量必须在30％以上。注释语言必须准确、易懂、简洁。

一、类注释以“/** */”的方式放在class 或者 interface 关键字以前，import 关键字以后

注释概要部分应要简明扼要，用简短的语句描述清除类的主要用途。注释可根据须要列出：做者、内容、功能、与其它类的关系等。

功能详细描述部分说明该类或者接口的功能、做用、使用方法和注意事项，每次修改后增长做者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，以下图：

类的注释

二、方法的注释，需列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、异常等，以下图所示：

方法的注释

三、对代码行的注释：注释应与其描述的代码相近，对代码的注释应放在其上方，并与其上面的代码用空行隔开，注释与所描述内容进行一样的缩排。

四、对代码进行修改时，应同步修改相应的注释，以保证注释与代码的一致性。再也不有用的注释要删除。

五、重写父类方法时必须进行@Override声明。

六、关键语句（条件分支、循环语句等）必须编写注释，精准的注释位置可帮助维护人员更好的理解程序，其效果有时比看设计文档要好的多。

七、方法内重要的单行代码用“//”注释，且注释语句与上句代码之间应空一行。

3、命名

一、包名采用域后缀倒置的加上自定义的包名，字母小写，均以com.xxxx开头(特殊状况除外)

在部门内部应该规划好包名的范围，防止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名称。除特殊缘由包结构都必须以com.xxxx开头，若是由于OEM合做等关系，能够不作要求。

二、类名和接口使用类意义完整的英文描述，英文单词的首字母使用大写、其他字母使用小写的大小写混合法，如：

OrderInformation, CustomerList, LogManager等

三、方法名使用意义完整的英文描述：第一个单词的字母使用小写、其他单词首字母大写其他字母小写的大小写混合法，如：

• public static boolean checkAuthorization(){……}

• public static String makeAuthorizationCode(){……}

四、相关方法中的存取属性的方法采用setter 和 getter方法，动做方法采用动词和动宾结构，如：

• get + 非布尔属性名()：public String getType();

• is + 布尔属性名()：public boolean isFinished();

• set + 属性名()：public void setVisible(boolean);

• 动词()：public void show();

• 动词 + 宾语()：public void addKey(Listener);
  

五、属性名使用完整的英文单词，首单词的字母小写，其余单词首字母大写其他字母小写，如：

• private orderNumber;

• private smpSession;

• private customerName;

六、避免使用学术专业术语（魔法数字等）看成变量，用有意义的常量名来替代。

如涉及物理状态或者含有物理意义的常量，不该直接使用数字或单个字母，必须用有意义的静态常量代替，如：

定义常量代替

七、常量名用大写英文描述，单词间用下划线分隔，且用 static final修饰，如：

• public static final int PAGE_SIZE = 100;

• public static final String DEFAULT_START_DATE = "2020-01-01";

八、数组采用“类型[] 数组名”的方式定义 ，而不用“类型 数组名[]”的方式定义，如：

• 可读性差：public String getCustomers()[]{ ....}

• 可读性强：public String[] getCustomers(){ ....}

九、如函数的名称大于15 个字母，则可去掉单词的元音字母或者以业内约定俗成的缩写方式命名，如：

可将 getCustomerInformation() 改成 getCustomerInfo()

十、集合类的属性命名时，应尽可能以其复数形式表意，如：

students, orderItems