上个月发布了Android项目重构的三篇系列文章,其中,界面篇中提到了在项目中保持规范性的重要性,也有简单举了几个例子。这篇文章则将其延伸,提供更完整的开发规范说明。
书写规范
public void method() { // Good}public void method(){ // Bad}public void method(){ // Bad}
if、else、for、switch、while等逻辑关键字与后面的语句留一个空格隔开。
// Goodif (booleanVariable) { // TODO while booleanVariable is true} else { // TODO else}// Badif(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,没有用一个空格隔开
将逻辑相关的代码段用空行隔开,以提高可读性。空行也只空一行,不要空多行。在以下情况需用一个空行:
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
private String param1; // 参数1private String param2; // 参数2
Windows:CTRL+ALT+L Mac:OPTION+COMMAND+L
// 用枚举类定义,Goodpublic enum CouponType { // 现金券 @SerializedName("1")
CASH, // 抵用券 @SerializedName("2")
DEBIT, // 折扣券 @SerializedName("3")
DISCOUNT
}// 用整型定义,Badpublic static final int TYPE_CASH = 1; // 现金券public static final int TYPE_DEBIT = 2; // 抵扣券public static final int TYPE_DISCOUNT = 3; // 折扣券
命名规范
域名反写+项目名称+模块名称,全部单词用小写字母。 例如,我的KAndroid项目的Model模块包名如下:
me.keeganlee.kandroid.model
使用大驼峰规则,用名词或名词词组命名,每个单词的首字母大写。 以下为几种常用类的命名:
使用小驼峰规则,用动词命名,第一个单词的首字母小写,其他单词的首字母大写。 以下为几种常用方法的命名:
控件 | 缩写 | 控件 | 缩写 |
---|---|---|---|
TextView | txt | EditText | edt |
Button | btn | ImageButton | ibtn |
ImageView | img | ListView | list |
RadioGroup | group | RadioButton | rbtn |
ProgressBar | progress | SeekBar | seek |
CheckBox | chk | Spinner | spinner |
TableLayout | table | TableRow | row |
LinearLayout | llayout | RelativeLayout | rlayout |
ScrollView | scroll | SearchView | search |
TabHost | host | TabWidget | widget |
全部为大写单词,单词之间用下划线分开。
public final static int PAGE_SIZE = 20;
{范围描述+}意义描述+类型描述的组合,用驼峰式,首字母小写。
private TextView headerTitleTxt; // 标题栏的标题private Button loginBtn; // 登录按钮private CouponBO couponBO; // 券实例
控件缩写_{范围_}意义,范围可选,只在有明确定义的范围内才需要加上。
<!-- 这是标题栏的标题 -->
<TextView
android:id="@+id/txt_header_title"
... />
<!-- 这是登录按钮 -->
<Button
android:id="@+id/btn_login"
... />
组件类型_{范围_}功能,范围可选,只在有明确定义的范围内才需要加上。 以下为几种常用的组件类型命名:
类型_{范围_}功能,范围可选。 以下为几种常用的命名:
前缀{_控件}{_范围}{_后缀},控件、范围、后缀可选,但控件和范围至少要有一个。
前缀{_控件}{_范围}{_后缀},控件、范围、后缀可选,但控件和范围至少要有一个。
动画类型_动画方向。
注释规范
文件顶部统一添加版权声明,声明的格式如下:
/**
* Copyright (c) 2015. Keegan小钢 Inc. All rights reserved.
*/
类和接口统一添加javadoc注释,格式如下:
/**
* 类或接口的描述信息
*
* @author ${USER}
* @date ${DATE}
*/
下面几种方法,都必须添加javadoc注释,说明该方法的用途和参数说明,以及返回值的说明。
/**
* 登录
*
* @param loginName 登录名
* @param password 密码
* @param listener 回调监听器
*/public void login(String loginName, String password, ActionCallbackListener<Void> listener);
下面几种情况下的常量和变量,都要添加注释说明,优先采用右侧//来注释,若注释说明太长则在上方添加注释。
public static final int TYPE_CASH = 1; // 现金券public static final int TYPE_DEBIT = 2; // 抵扣券public static final int TYPE_DISCOUNT = 3; // 折扣券private int id; // 券idprivate String name; // 券名称private String introduce; // 券简介
结束语
这份开发规范说明比较细,也许还不是非常完整,但里面提到的每一条规范都很有用。按照此规范严格执行,将大大提高代码的可读性和维护性。