1.命名规范
命名方法很多,但是比较有名的且被广泛接受的命名法包括下面两种。
匈牙利命名,一般只是命名变量,原则是:变量名 = 类型前缀 + 描述,如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等。
2.注释规范
Java中注释的语法有三种:单行注释(//)、多行注释(/*...*/)和文档注释(/**...*/)。本节介绍如何规范使用这些注释。
2.1 文件注释
文件注释就是在每一个文件开头添加注释。文件注释通常包括如下信息:版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。
下面看一个文件注释的示例:
/*
* 版权所有 2015 XX有限公司
* 许可信息查看LICENSE.txt文件
* 描述:
* 实现日期基本功能
* 历史版本:
* 2015-7-22: 创建 XX
* 2015-8-20: 添加socket库
* 2015-8-22: 添加math库
*/
2.2 文档注释
文档注释就是指这种注释内容能够生成API帮助文档,JDK中javadoc命令能够提取这些注释信息并生成HTML文件。文档注释主要对类(或接口)、实例变量、静态变量、实例方法和静态方法等进行注释。
注意:文档是要给别人看的帮助文档,一般注释的实例变量、静态变量、实例方法和静态方法都应该是非私有的,那些只给自己看的内容可以不用文档注释。
由于文档注释最终会生成HTML文档,所以可以在文档注释中使用HTML标签,如
是HTML段落标签。另外,文档注释中还可以用@author、@return和@param等文档注释标签,这些标签能够方便生成API帮助文档。
文档注释标签:
想生成API帮助文档,可以使用javadoc指令:javadoc -d apidoc Data.java
-d参数指明要生成文档的目录,apidoc是当前目录下面的apidoc目录,如果不存在javadoc会创建一个apidoc目录;Data.java是当前目录下的Java源文件。
如果生成成功则在当前apidoc目录下生成很多HTML文件,其中的index.html文件是文档的入口。
2.3 代码注释
程序代码中处理文档注释还需要在一些关键的地方添加代码注释,文档注释一般是给一些看不到源代码的人看的帮助文档,而代码注释是给阅读源代码的人参考的。代码注释一般是采用单行注释(//)和多行注释(/*...*/)。
2.4 地标注释
在代码中加一些标识,便于IDE工具快速定位代码,称为“地标注释”。这种注释虽然不是Java官方所提供的,但是主流语言和主流的IDE工具也都支持“地标注释”。
TODO:说明此处有待处理的任务,或代码没有编写完成。
FIXME:说明此处代码是错误的,需要修正。
XXX:说明此处代码虽然实现了功能,但是实现的方法有待商榷,希望将来能改进。
3.代码排版
代码排版包括空行、空格、断行和缩进等内容。代码排版内容比较多,工作量很大,也非常重要。
3.1 空行
空行用以将逻辑相关的代码段分隔开,以提高可读性。空行使用规范:
类声明和接口声明之间保留两个空行。
两个方法之间保留一个空行。
方法的第一条语句之前保留一个空行。
代码注释(尾端注释外)之前保留一个空行。
一个方法内的两个逻辑段之间。
3.2 空格
代码中的有些位置是需要有空格的,这个工作量也很大。下面是使用空格的规范:
赋值符号“=”前后各有一个空格。
所有的二元运算符都应该使用空格与操作数分开。
一元操作符:负号“-”、自增“++”和自减“--”等,它们与操作数之间没有空格。
小左括号“(”之后,小右括号“)”之前不应有空格。
大左括号“{”之前有一个空格。
方法参数列表小左括号“(”之前没有空格,小右括号“)”之后有一个空格,参数列表中参数逗号“,”之后也有一个空格。
关键字之后紧跟着小左括号“(”,关键字之后应该有一个空格。
3.3 缩进
缩进可以依据一般规范,如下。
在方法、Lambda、控制语句等包含大括号“{}”的代码块中,代码块的内容相对于首行缩进一个级别(4个空格)。
如果是if语句中条件表达式的断行,那么新的一行应该相对于上一行缩进两个级别(8个空格),再往后的断行要与第一次的断行对齐。
3.4 断行
一行代码的长度应尽量不要超过80个字符,如果超过则需断行,可以依据下面的一般规范断开:
在一个逗号后面断开。
在一个操作符前面断开,要选择较高级别的运算符(而非较低级别的运算符)断开。
新的一行应该相对于上一行缩进两个级别(8个空格)。
4.其他规范
在声明变量或常量时推荐一行一个声明。
左大括号“{”位于声明语句同行的末尾。右大括号“}”另起一行,与相应的声明语句对齐,除非是一个空语句,右大括号“}”应紧跟在左大括号“{”之后。
每行至多包含一条语句。
虽然Java语言允许if、for等控制语句只有一行代码情况下,省略左右两个大括号,但是编码规范并不推荐这样使用。