书写规范
- 花括号不要单独一行,和它前面的代码同一行。而且,花括号与前面的代码之间用一个空格隔开。
public void method() { // Good } public void method() { // Bad } public void method(){ // Bad }
- if、else、for、switch、while等逻辑关键字与后面的语句留一个空格隔开。
// Good if (booleanVariable) { // TODO while booleanVariable is true } else { // TODO else } // Bad if(booleanVariable) { // TODO while booleanVariable is true }else { // TODO else }
- 运算符两边各用一个空格隔开。
int result = a + b; //Good, = 和 + 两边各用一个空格隔开 int result=a+b; //Bad,=和+两边没用空格隔开
- 方法的每个参数之间用一个空格隔开。
public void method(String param1, String param2); // Good,param1后面的逗号与String之间隔了一个空格 method(param1, param2); // Good,方法调用时,param1后面的逗号与param2之间隔了一个空格 method(param1,param2); // Bad,没有用个空格隔开
- 空行的使用
将逻辑相关的代码段用空行隔开,以提高可读性。空行也只空一行,不要空多行。在以下情况需用一个空行:
两个方法之间
方法内的两个逻辑段之间
方法内的局部变量和方法的第一条逻辑语句之间
常量和变量之间
- 当一个表达式无法容纳在一行内时,可换行显示,另起的新行用8个空格缩进。
someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);
- 一行声明一个变量,不要一行声明多个变量,这样有利于写注释。
private String param1; // 参数1 private String param2; // 参数2
- 一个方法最多不要超过40行代码。
- 范围型的常量用枚举类定义,而不要直接用整型或字符,这样可以减少范围值的有效性检查。
// 用枚举类定义,Good public enum CouponType { // 现金券 @SerializedName("1") CASH, // 抵用券 @SerializedName("2") DEBIT, // 折扣券 @SerializedName("3") DISCOUNT } // 用整型定义,Bad public static final int TYPE_CASH = 1; // 现金券 public static final int TYPE_DEBIT = 2; // 抵扣券 public static final int TYPE_DISCOUNT = 3; // 折扣券
- 水平对齐:不做强制要求
private int x ; // this is fine private Color color ; // this too private int x ; // permitted, but future edits private Color color ; // may leave it unaligned
命名规范
- 包命名
包名全部用小写字母,通过 . 将各级连在一起。不应该使用下划线。
com.shaonaozu.application
- 类和接口的命名
类型的命名,采用以大写字母开头的大小写字符间隔的方式(UpperCamelCase)。
class命名一般使用名词或名词短语。interface的命名有时也可以使用形容词或形容词短语。
测试类的命名,应该以它所测试的类的名字为开头,并在最后加上Test结尾。例如:HashTest 、 HashIntegrationTest。
- 方法的命名
方法命名,采用以小写字母开头的大小写字符间隔的方式(lowerCamelCase)。
方法命名一般使用动词或者动词短语。
初始化方法,命名init开头,比如:initView
按钮点击方法,命名以to开头,比如:toLogin
设置方法,以set开头,比如:setData
具有返回值的获取方法,以get开头,比如:getData
通过异步加载数据的方法,以load开头,比如:loadData
布尔型的判断方法,以is或has,或具有逻辑意思的单词如equals,例如:isEmpty
添加数据,以add开头,例如:addData
修改数据,以modify开头,例如:modifyData
删除数据,以delete开头,比如:deleteData
- 常量命名
常量命名,全部使用大写字符,词与词之间用下划线隔开。(CONSTANCE_CASE)。
常量一般使用名词或者名词短语命名。
static final int NUMBER =5; static final SomeEnum { ENUM_CONSTANT }
- 非常量的成员变量名
非常量的成员变量命名(包括静态变量和非静态变量),采用lowerCamelCase命名。
一般使用名词或名词短语。
- 参数名
参数命名采用lowerCamelCase命名。
应该避免使用一个字符作为参数的命名方式。
- 局部变量名
局部变量采用lowerCamelCase命名。它相对于其他类型的命名,可以采用更简短宽松的方式。
但即使如此,也应该尽量避免采用单个字母进行命名的情况,除了在循环体内使用的临时变量。
即使局部变量是final、不可改变的,它也不能被认为是常量,也不应该采用常量的命名方式去命名。
- 静态成员的访问:应该通过类,而不是对象
当一个静态成员被访问时,应该通过class名去访问,而不应该使用这个class的具体实例对象。
class Foo { static aStaticMethod() { } } Foo aFoo = ...; Foo.aStaticmethod(); //good aFoo.aStaticmethod(); //bad
Javadoc
- 通用格式
或单行格式/** * Multiple lines of Javadoc text are written here * wrapped normally ... */ public int method(String p1) {...}
/** An especially short bit of javaodc */
- 段落
空白行:是指javadoc中,上下两个段落之间只有上下对齐的 * 字符的行。每个段落的第一行在第一个字符之前,有一个<p>标签,并且之后不要有任何空格。
/** * Multiple lines of Javadoc text are written here * <p>wrapped normally ...</p> */ public int method(String p1) {...}
- @从句
所有标准的@从句,应该按照如下的顺序添加:@param、@return、@throws、@deprecated。并且这四种@从句,不应该出现在一个没有描述的Javadoc块中。
当@从句无法在一行写完时,应该断行。延续行在第一行的@字符的位置,缩进至少4个字符单位。
/** * @param model 描述描述描述描述描述描述描述 * 描述描述描述描述描述 * @param request * @return * @throws * @deprecated */
- 何处应该使用Javadoc
至少,Javadoc应该应用于所有的public类、public和protected的成员变量和方法。和少量例外的情况。例外情况如下。
例外:方法本身已经足够说明的情况
当方法本身很显而易见时,可以不需要javadoc。例如:getFoo。没有必要加上javadoc说明“Returns the foo”。
单元测试中的方法基本都能通过方法名,显而易见地知道方法的作用。因此不需要增加javadoc。
注意:有时候不应该引用此例外,来省略一些用户需要知道的信息。例如:getCannicalName 。当大部分代码阅读者不知道canonical name是什么意思时,不应该省略Javadoc,认为只能写/** Returns the canonical name. */ 。
例外:重载方法
重载方法有时不需要再写Javadoc。