Android开发代码规范

Android开发代码规范

 

1. 前言

这份文档参考了  Google 官方 Android 编码风格规范。该文档仅供参考，只要形成一个统一的风格，见者知其意即可。

1.1 术语说明

在本文档中，除非另有说明：

1.       术语 class 可表示一个普通类，枚举类，接口或是annotation类型(@interface)

2.       术语 comment 只用来指代实现的注释(implementationcomments)，我们不使用”documentation comments”一词，而是用 Javadoc。其他的术语说明会偶尔在后面的文档出现。

1.2 指南说明本文档中的示例代码并不作为规范，仅供参考。

基本格式方面使用AndroidStudio 默认模板即可（使用格式化快捷键处理后基本符合）。

2. 源文件基础

2.1 文件名

源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。

2.2 文件编码：UTF-8

源文件编码格式为 UTF-8。

3. 源文件结构

一个源文件包含(按顺序地)：

1.       许可证或版权信息(如有需要)

2.       package语句

3.       import语句

3.1 许可证或版权信息

如果一个文件包含许可证或版权信息，那么它应当被放在文件最前面。

3.2 package语句

package 语句不换行，列限制并不适用于package语句。(即package语句写在一行里)

3.3 import语句

3.3.1 import不要使用通配符

即，不要出现类似这样的import语句：importjava.util.*;

3.3.2 不要换行

import语句不换行，列限制并不适用于import语句。(每个import语句独立成行)

3.4 类声明

3.4.1 只有一个顶级

类声明每个顶级类都在一个与它同名的源文件中(当然，还包含.java后缀)。
例外：package-info.java，该文件中可没有package-info类。

3.4.2 类成员顺序

类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。

最重要的一点，每个类应该以某种逻辑去排序它的成员，维护者应该要能解释这种排序逻辑。比如，新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。

3.4.2.1 区块划分

建议使用注释将源文件分为明显的区块，区块划分如下

1.       常量声明区

2.       UI控件成员变量声明区

3.       普通成员变量声明区

4.       内部接口声明区

5.       初始化相关方法区

6.       事件响应方法区

7.       普通逻辑方法区

8.       重载的逻辑方法区

9.       发起异步任务方法区

10.     异步任务回调方法区

11.     生命周期回调方法区（除去onCreate()方法）

12.     内部类声明区

3.4.2.2 类成员排列通用规则

1.       按照发生的先后顺序排列

2.       常量按照使用先后排列

3.       UI控件成员变量按照layout文件中的先后顺序排列

4.       普通成员变量按照使用的先后顺序排列

5.       方法基本上都按照调用的先后顺序在各自区块中排列

6.       相关功能作为小区块放在一起（或者封装掉）

4. 格式术语

说明：块状结构(block-likeconstruct)指的是一个类，方法或构造函数的主体。

4.1 大括号

4.1.1 使用大括号(即使是可选的)

大括号与if, else,for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。

4.1.2 非空块：K & R 风格

对于非空块和块状结构，大括号遵循 Kernighan 和 Ritchie 风格 (Egyptianbrackets):·

·        左大括号前不换行·

·        左大括号后换行·

·        右大括号前换行·

·        如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。

例如，如果右大括号后面是else或逗号，则不换行。

示例：

returnnew MyClass() {   

    @Overridepublic void method() {       

        if (condition()) {

            try {

               something();

            } catch (ProblemException e) {

               recover();

            }

        }

    }

};

4.1.3 空块：可以用简洁版本

一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。

例外：如果它是一个多块语句的一部分(if/else 或try/catch/finally) ，即使大括号内没内容，右大括号也要换行。
示例：

voiddoNothing() {}

4.2 块缩进：4个空格

每当开始一个新的块，缩进增加4个空格，当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见4.1.2节中的代码示例)

4.3 一行一个语句

每个语句后要换行。

4.4自动换行

术语说明：一般情况下，一行长代码为了避免超出列限制(80或100个字符)而被分为多行，我们称之为自动换行(line-wrapping)。我们并没有全面，确定性的准则来决定在每一种情况下如何自动换行。很多时候，对于同一段代码会有好几种有效的自动换行方式。

Tip:提取方法或局部变量可以在不换行的情况下解决代码过长的问题(是合理缩短命名长度吧)

4.4.1 自动换行时缩进至少+4个空格

自动换行时，第一行后的每一行至少比第一行多缩进4个空格。当存在连续自动换行时，缩进可能会多缩进不只4个空格(语法元素存在多级时)。一般而言，两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。

4.5 空白

4.5.1 垂直空白

以下情况需要使用一个空行：

1.       类内连续的成员之间：字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块。例外：两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组。

2.       在函数体内，语句的逻辑分组间使用空行。

3.       类内的第一个成员前或最后一个成员后的空行是可选的(既不鼓励也不反对这样做，视个人喜好而定)。

4.       要满足本文档中其他节的空行要求

5.       多个连续的空行是允许的，但没有必要这样做(我们也不鼓励这样做)。

4.5.2 水平对齐：不做要求

术语说明：水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。
这是允许的(而且在不少地方可以看到这样的代码)，但Google编程风格对此不做要求。即使对于已经使用水平对齐的代码，我们也不需要去保持这种风格。

以下示例先展示未对齐的代码，然后是对齐的代码：

privateint x; // this is fine

private Color color; // this too

privateint    x;         // permitted, but future edits

private Color  color;     // may leave it unaligned

Tip：对齐可增加代码可读性，但它为日后的维护带来问题。考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。
这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格)。
这就会让你做许多的无用功，增加了reviewer的工作并且可能导致更多的合并冲突。

5. 命名约定

5.1 对所有标识符都通用的规则

标识符只能使用ASCII字母和数字，因此每个有效的标识符名称都能匹配正则表达式\w+。

5.2 标识符类型的规则

5.2.1 包名

包名全部小写，连续的单词只是简单地连接起来，不使用下划线。

采用反域名命名规则，全部使用小写字母。一级包名为com，二级包名为xx（可以是公司或则个人的随便），三级包名根据应用进行命名，四级包名为模块名或层级名。

例如：com.jiashuangkuaizi.kitchen

包名	此包中包含
com.xx.应用名称缩写.activity	页面用到的Activity类 (activitie层级名用户界面层)
com.xx.应用名称缩写.base	基础共享的类
com.xx.应用名称缩写.adapter	页面用到的Adapter类 (适配器的类)
com.xx.应用名称缩写.util	此包中包含：公共工具方法类（util模块名）
com.xx.应用名称缩写.bean	下面可分：vo、po、dto 此包中包含：JavaBean类
com.xx.应用名称缩写.model	此包中包含：模型类
com.xx.应用名称缩写.db	数据库操作类
com.xx.应用名称缩写.view (或者 com.xx.应用名称缩写.widget )	自定义的View类等
com.xx.应用名称缩写.service	Service服务
com.xx.应用名称缩写.receiver	BroadcastReceiver服务

5.2.2 类名

类名都以UpperCamelCase风格编写。

类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。

名词，采用大驼峰命名法，尽量避免缩写，除非该缩写是众所周知的，比如HTML,URL，如果类名称中包含单词缩写，则单词缩写的每个字母均应大写。

类	描述	例如
Activity 类	Activity为后缀标识	欢迎页面类WelcomeActivity
Adapter类	Adapter 为后缀标识	新闻详情适配器 NewDetailAdapter
解析类	Parser为后缀标识	首页解析类HomePosterParser
工具方法类	Util或Manager为后缀标识（与系统或第三方的Utils区分）或功能+Util	线程池管理类：ThreadPoolManager日志工具类：LogUtil（Logger也可）打印工具类：PrinterUtil
数据库类	以DBHelper后缀标识	新闻数据库：NewDBHelper
Service类	以Service为后缀标识	时间服务TimeServiceBroadcast
Receiver类	以Receiver为后缀标识	推送接收JPushReceiver
ContentProvider	以Provider为后缀标识
自定义的共享基础类	以Base开头	BaseActivity,BaseFragment

测试类的命名以它要测试的类的名称开始，以Test结束。

例如：HashTest 或HashIntegrationTest。

接口（interface）：命名规则与类一样采用大驼峰命名法，多以able或ible结尾，如

interfaceRunnable ;
interface Accessible。

注意：
如果项目采用MVP，所有Model、View、Presenter的接口都以I为前缀，不加后缀，其他的接口采用上述命名规则。

5.2.3 方法名

方法名都以LowerCamelCase 风格编写。

方法名通常是动词或动词短语。

方法	说明
initXX()	初始化相关方法,使用init为前缀标识，如初始化布局initView()
isXX() checkXX()	方法返回值为boolean型的请使用is或check为前缀标识
getXX()	返回某个值的方法，使用get为前缀标识
handleXX()	对数据进行处理的方法，尽量使用handle为前缀标识
displayXX()/showXX()	弹出提示框和提示信息，使用display/show为前缀标识
saveXX()	与保存数据相关的，使用save为前缀标识
resetXX()	对数据重组的，使用reset前缀标识
clearXX()	清除数据相关的
removeXXX()	清除数据相关的
drawXXX()	绘制数据或效果相关的，使用draw前缀标识

下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是：test_，例如testPop_emptyStack。

并不存在唯一正确的方式来命名测试方法。

5.2.4 常量名

常量名命名模式为CONSTANT_CASE，全部字母大写，用下划线分隔单词。那，到底什么算是一个常量？

每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时，考虑它是否真的感觉像是一个常量。

例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。

// Constants

staticfinalint NUMBER = 5;

staticfinal ImmutableListNAMES = ImmutableList.of("Ed", "Ann");

staticfinal Joiner COMMA_JOINER = Joiner.on(','); //because Joiner is immutable

staticfinal SomeMutableType[] EMPTY_ARRAY = {};

enum SomeEnum { ENUM_CONSTANT }

// Not constants

static String nonFinal = "non-final";

final String nonStatic = "non-static";

staticfinal SetmutableCollection = new HashSet();

staticfinal ImmutableSetmutableElements = ImmutableSet.of(mutable);

staticfinal Logger logger = Logger.getLogger(MyClass.getName());

staticfinal String[] nonEmptyArray = {"these", "can", "change"};

这些名字通常是名词或名词短语。

5.2.5 参数名

参数名以LowerCamelCase风格编写

5.2.6 局部变量名

局部变量名以LowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。

虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。

即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。

临时变量

临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。如： for (int i =0; i < len ; i++)，并且它和第一个单词间没有空格。

5.2.7 类型变量名

类型变量可用以下两种风格之一进行命名：

·        单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)。

·        以类命名方式(5.2.2节)，后面加个大写的T(如：RequestT,FooBarT)。

5.2.8 资源文件命名规范

1. 资源布局文件（XML文件（layout布局文件））：

全部小写，采用下划线命名法
1) contentview 命名
必须以全部单词小写，单词间以下划线分割，使用名词或名词词组。
所有Activity或Fragment的contentView必须与其类名对应，对应规则为：
将所有字母都转为小写，将类型和功能调换（也就是后缀变前缀）。
例如：activity_main.xml

2) Dialog命名：dialog_描述.xml
例如：dialog_hint.xml

3) PopupWindow命名：ppw_描述.xml
例如：ppw_info.xml

4) 列表项命名：item_描述.xml
例如：item_city.xml

5) 包含项命名： include_位置_模块_描述.xml
例如： include_head_xxxx.xml、include_bottom_xxxx.xml
2. 资源文件（图片drawable文件夹下）：
全部小写，采用下划线命名法，加前缀区分
命名模式：可加后缀 _small 表示小图, _big 表示大图，逻辑名称可由多个单词加下划线组成，采用以下规则：
用途_模块名_逻辑名称
用途_模块名_颜色
用途_逻辑名称
用途_颜色
说明：用途也指控件类型（具体见UI控件缩写表）
例如：
btn_main_home.png 按键
divider_maket_white.png 分割线
ic_edit.png 图标
bg_main.png 背景
btn_red.png 红色按键
btn_red_big.png 红色大按键
ic_head_small.png 小头像
bg_input.png 输入框背景
divider_white.png 白色分割线
如果有多种形态如按钮等除外如 btn_xx.xml（selector）

名称	功能
btn_xx	按钮图片使用btn_整体效果（selector）
btn_xx_normal	按钮图片使用btn_正常情况效果
btn_xx_pressed	按钮图片使用btn_点击时候效果
btn_xx_focused	state_focused聚焦效果
btn_xx_disabled	state_enabled (false)不可用效果
btn_xx_checked	state_checked选中效果
btn_xx_selected	state_selected选中效果
btn_xx_hovered	state_hovered悬停效果
btn_xx_checkable	state_checkable可选效果
btn_xx_activated	state_activated激活的
btn_xx_windowfocused	state_window_focused
bg_head	背景图片使用bg_功能_说明
def_search_cell	默认图片使用def_功能_说明
ic_more_help	图标图片使用ic_功能_说明
seg_list_line	具有分隔特征的图片使用seg_功能_说明
sel_ok	选择图标使用sel_功能_说明

注意：

使用AndroidStudio的插件SelectorChapek可以快速生成selector，前提是命名要规范。

3. 动画文件（anim文件夹下）：

全部小写，采用下划线命名法，加前缀区分。
具体动画采用以下规则：
模块名_逻辑名称
逻辑名称
refresh_progress.xml
market_cart_add.xml
market_cart_remove.xml
普通的tween动画采用如下表格中的命名方式
// 前面为动画的类型，后面为方向

动画命名例子	规范写法
fade_in	淡入
fade_out	淡出
push_down_in	从下方推入
push_down_out	从下方推出
push_left	推向左方
slide_in_from_top	从头部滑动进入
zoom_enter	变形进入
slide_in	滑动进入
shrink_to_middle	中间缩小

4. values中name命名

类别	命名	示例
strings	strings的name命名使用下划线命名法，采用以下规则：模块名+逻辑名称	main_menu_about 主菜单按键文字friend_title 好友模块标题栏friend_dialog_del 好友删除提示login_check_email 登录验证 dialog_title 弹出框标题 button_ok 确认键 loading 加载文字
colors	colors的name命名使用下划线命名法，采用以下规则：模块名+逻辑名称颜色	friend_info_bg friend_bg transparent gray
styles	styles的name命名使用 Camel命名法，采用以下规则：模块名+逻辑名称	main_tabBottom

5. layout中的id命名

命名模式为：view缩写_view的逻辑名称
使用AndroidStudio 的插件 ButterKnife Zelezny，生成注解非常方便。
如果不使用 ButterKnifeZelezny，则建议使用 view 缩写做后缀，如：username_tv（展示用户名的TextView）

 

附录：

表1 UI控件缩写表

控件	缩写	例子
LinearLayout	ll	llFriend或者mFriendLL
RelativeLayout	rl	rlMessage或mMessageRL
FrameLayout	fl	flCart或mCartFL
TableLayout	tl	tlTab或mTabTL
Button	btn	btnHome或mHomeBtn
ImageButton	ibtn	btnPlay或mPlayIBtn
TextView	tv	tvName或mNameTV
EditText	et	etName或mNameET
ListView	lv	lvCart或mCartLV
ImageView	iv	ivHead或mHeadIV
GridView	gv	gvPhoto或mPhotoGV

表2 常见的英文单词缩写:

名称	缩写
icon	ic （主要用在app的图标）
color	cl（主要用于颜色值）
divider	di（主要用于分隔线，不仅包括Listview中的divider，还包括普通布局中的线）
selector	sl（主要用于某一view多种状态，不仅包括Listview中的selector，还包括按钮的selector）
average	avg
background	bg（主要用于布局和子布局的背景）
buffer	buf
control	ctrl
delete	del
document	doc
error	err
escape	esc
increment	inc
infomation	info
initial	init
image	img
Internationalization	I18N
length	len
library	lib
message	msg
password	pwd
position	pos
server	srv
string	str
temp	tmp
window	wnd(win)

程序中使用单词缩写原则：不要用缩写，除非该缩写是约定俗成的。