Android 软件开发规范说明

应公司需要，特整理了一套Android软件开发的规范，仅供参考。

不知道为什么目录会排版混乱，调不过来。直接看内容吧。。。。

1、引言

1.1 目的

本文档编写的目的是为了便于Android项目团队各成员间的协同开发，提高项目代码的质量，增强代码的可读性和可维护性。

本文档的预期读者为：Android开发人员、维护人员等。

1.2 背景

一个软件的生命周期中，少部分时间用于开发，大部分时间用于维护，就开发阶段而言，项目团队的协同开发，需要按照统一的标准执行，以提高开发效率。就维护阶段而言，因为软件不一定会由最初的开发人员来维护，这就需要规范的开发和维护标准，以保证软件的易维护性。

1.3 预期读者与阅读建议

	阅读建议
Android开发人员	仔细阅读全部内容。
Android维护人员	仔细阅读全部内容。

2、开发环境

2.1 Eclipse编码格式

Eclipse需要采用统一的编码环境，配置如下：
window->Preferences->general->Workspace，右侧Text file encoding，选择Other，改变为UTF-8，以后新建立工程其属性对话框中的Text file encoding即为UTF-8. 

window->Preferences->general->Content Types，右侧Context Types树，点开Text，选择Java Source File，在下面的Default encoding输入框中输入UTF-8，点Update，则设置Java文件编码为UTF-8。其他java应用开发相关的文件如： properties、XML等已经由Eclipse缺省指定，分别为ISO8859-1，UTF-8，如开发中确需改变编码格式则可以在此指定。

2.2 Tab与空格

编码中不允许出现Tab符号，所有的Tab需用4个空格来代替，请用如下方法配置： Window->Preferences->General->Editors->Text Editors->Insert spaces for tabs。

XML文件的Tab格式也需要单独配置一下，用如下方法配置:Window->Preferences->XML->XML Files->Editor。

2.3 空行

空行将逻辑相关的代码段分隔开，以提高可读性。

      下列情况应该总是使用空行：

l  一个源文件的两个片段(section)之间。

l  类声明和接口声明之间。

l  两个方法之间。

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

l  一个方法内的两个逻辑段之间，用以提高可读性。

3、命名规则

3.1 标识命名法

l 驼峰(Camel)命名法:又称小驼峰命名法，除首单词外，其余所有单词的第一个字母大写。常用在变量、方法命名中，如pwdField、getUserName()等。常用在变量、方法命名中，如pwdField、getUserName()等。

l 帕斯卡(Pascal)命名法:又称大驼峰命名法，所有单词的第一个字母大写。常用在类命名中，如MainActivity等。

l 下划线命名法:单词与单词间用下划线做间隔。常用在布局文件命名中，如activity_main。

l 匈牙利命名法（不建议采用）:在每个变量名的前面加上若干表示数据类型的字符。基本原则是：变量名=属性+类型+对象描述。如i表示int,所有i开头的变量命都表示int类型。s表示String，所有变量命以s开头的都表示String类型变量。

3.2 英文缩写原则

l 较短的单词可通过去掉“元音”形成缩写。如：icon（ic）、selector(sl)等。

l 较长的单词可取单词的头几个字母形成缩写。如：listview（lv）等。

l 此外还有一些约定成俗的英文单词缩写。如：password（pwd）等。

3.3 包命名（package）

采用反域名命名规则，全部使用小写字母。一级包名为com，二级包名为xx（一般为公司名缩写），三级包名根据应用进行命名，四级包名为模块名或层级名。

包名	内容
com.xx.应用名称缩写.activities	页面用到的Activity类 (activities层级名用户界面层)
com.xx.应用名称缩写.base	页面中每个Activity类共享的可以写成一个i额BaseActivity类 (基础共享的类)
com.xx.应用名称缩写.adapter	页面用到的Adapter类 (适配器的类)
com.xx.应用名称缩写.tools	此包中包含：公共工具方法类（tools模块名）
com.xx.应用名称缩写.bean(或则 com.xx.应用名称缩写.unity)	此包中包含：元素类
com.xx.应用名称缩写.db	数据库操作类
com.xx.应用名称缩写.view(或则 com.xx.应用名称缩写.ui)	自定义的View类等
com.xx.应用名称缩写.service	Service服务
com.xx.应用名称缩写.broadcast	Broadcast服务

3.4 类、接口命名（class、interface）

    不能使用中文字符，不能在命名字符串中出现“0-9”的数值描述和除下划线以外的其他字符描述，命名的字母组合尽量能够在本身的文字意义上初步了解类的大体功能。

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

类、接口	描述	例如
activity 类	Aty或者Activity为后缀标识	欢迎页面类WelcomeAty.或者WelcomeActivity
Adapter类	Adp或者Adapte为后缀标识	新闻详情适配器NewtDetailAdp或则直接NewDetailAdapter
解析类	Hlr为后缀标识	首页解析类HomePosterHlr
公共方法类	Tools或Manager为后缀标识	线程池管理类：ThreadPoolManager、日志工具类：LogTools
数据库类	以DBHelper后缀标识	新闻数据库：NewDBHelper
Service类	以Service为后缀标识	时间服务TimeService
BroadcastReceive类	以Broadcast为后缀标识	时间通知TimeBroadcast
ContentProvider	以Provider为后缀标识
直接写的共享基础类	以Base开头	BaseActivity,BaseFragment
接口	多以Interface、able或ible结尾，或以“I”开头

3.5 方法命名（method）

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

3.6 变量命名（variable）

       采用小驼峰命名法。类中控件名称必须与xml布局id保持一致。

       所有静态变量都建议以s开头，例如：“sMobileNumber” 

       所有的非静态变量建议以m开头，例如：“mMobileNumber” 

       所有成员变量必须都定义在类的开始，定义顺序如下：常量->public 变量->private 变量 

3.7 常量命名（constant）

       全部大写，采用下划线命名法。例如：MIN_WIDTH。

3.8 资源文件命名

3.8.1 drawable资源命名

       全部小写，采用下划线命名法，加前缀区分。

       命名模式：activity名称_逻辑名称/common_逻辑名称。

       如果有多种形态如按钮等除外如btn_xx.xml（selector）。

名称	功能
btn_xx	按钮图片使用btn_整体效果（selector）
btn_xx_normal	按钮图片使用btn_正常情况效果
btn_xx_press	按钮图片使用btn_点击时候效果
bg_head	背景图片使用bg_功能_说明
def_search_cell	默认图片使用def_功能_说明
icon_more_help	图标图片使用icon_功能_说明
seg_list_line	具有分隔特征的图片使用seg_功能_说明
sel_ok	选择图标使用sel_功能_说明

       命名后缀：

后缀	说明
unit	在使用xml的tilemode来配图片时，element图片使用此后缀
nor	图片的状态，代表普通状态
hl	图片的状态，代表高亮状态
press	图片的状态，代表按下状态
select	图片的状态，代表其所占的view被选中
unselect	图片的状态，代表其所占的view没有被选中

3.8.2 layout布局文件命名

     全部小写，采用下划线命名法。

l  contentview命名，Activity默认布局，以去掉后缀的Activity类进行命名。不加后缀：功能模块.xml

例如：main.xml、more.xml、settings.xml

      或者：activity_功能模块.xml

     例如：activity_main.xml、activity_more.xml

l  Dialog命名：dialog_描述.xml

              例如：dlg_hint.xml

l  PopupWindow命名：ppw_描述.xml

       例如：ppw _info.xml

l  列表项命名listitem_描述.xml

              例如：listitem_city.xml

l  包含项：include_模块.xml

              例如：include_head.xml、include_bottom.xml

l  adapter的子布局：功能模块_item.xml

              例如：main_item.xml

3.8.3 anim动画文件命名

       全部小写，采用下划线命名法，加前缀区分。

动画命名例子	规范写法	说明
fade_in	淡入	前面为动画的类型，后面为方向
fade_out	淡出
push_down_in	从下方推入
push_down_out	从下方推出
push_left	推像左方
slide_in_from_top	从头部滑动进入
zoom_enter	变形进入
slide_in	滑动进入
shrink_to_middle	中间缩小

3.8.4 资源ID（resourceid）命名

       大小写规范与方法名一致，采用小驼峰命名法。命名规范为“资源控件的缩写名”+“变量名”。

       strings.xml，colors.xml等中的id命名：

       命名模式：activity名称_功能模块名称_逻辑名称/activity名称_逻辑名称/common_逻辑名称。

       strings.xml中，使用activity名称注释，将文件内容区分开来。

3.8.5 layout中的id命名

       命名模式为：view缩写_模块名称_view的逻辑名称。

view的缩写参照如下：

控件	缩写	控件	缩写	控件	缩写
LayoutView	lv	toggleButton	tglBtn	ImageSwitch	imgSwt
RelativeView	rv	ProgressBar	proBar	listView	lVi 或lv
TextView	tv	SeekBar	skBar	ExpandableList	epdLt
Button	btn	AutoCompleteTextView	autoTxt	MapView	mapVi
ImageButton	imgBtn	ZoomControls	zmCtl	Chronometer	cmt
ImageView	mgView 或iv	VideoView	vdoVi	ScollView	sclVi
CheckBox	chk	WdbView	webVi	TextSwitch	txtSwt
RadioButton	rdoBtn	RantingBar	ratBar	DatePicker	dtPk
analogClock	anaClk	Tab	tab	EditText	edtTxt
DigtalClock	dgtClk	Spinner	spn	TimePicker	tmPk

3.8.6 activity中view变量命名

       命名模式为：逻辑名称+view缩写

建议：如果layout文件很复杂，建议将layout分成多个模块，每个模块定义一个moduleViewHolder，其成员变量包含所属view。

3.8.7 style.xml命名

      将layout中不断重现的style提炼出通用的style通用组件，放到styles.xml中。

4、注释

    注释有助于理解代码，有效的注释是指在代码的功能、意图层次上进行注释，提供有用、额外的信息，而不是代码表面意义的简单重复。

       Java 程序有两类注释：实现注释(implementation comments)和文档注释(documentcomments)。实现注释是使用/*...*/和//界定的注释。文档注释(被称为"doc comments")由/**...*/界定。文档注释可以通过javadoc 工具转换成HTML 文件。

4.1 文件注释

   所有的源文件都应该在开头有一个注释，其中列出文件的功能描述以及创建、修改记录：

/**

  * 文件功能

 * 版本信息，版本号

 * 创建日期

 */

4.2 类或接口注释

采用JavaDoc文档注释，在类、接口定义之前应当对其进行注释，包括类、接口的描述、最新修改者、版本号、参考链接等。

/** 

 * 描述

 * @author 作者（最新修改者）

 * @version 版本号（最新版本号）

 * @see 参考的JavaDoc

 */

       注：JavaDoc文档注释：描述Java的类、接口、构造方法、方法、以及字段。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前。文档注释的第一行(/**)不需缩进，随后的文档注释每行都缩进1格(使星号纵向对齐)。

4.3 方法注释

 采用JavaDoc文档注释，在方法定义之前当对其进行注释，包括方法的描述、输入、输出及返回值说明、抛出异常说明、参考链接等。

/**

 * 描述

 * @param 参数说明：每个参数一行，注明其取值范围等

 * @return 返回值：注释出失败、错误、异常时的返回情况

 * @exception 异常：注释出什么条件下会引发什么样的异常

 * @see 参考的JavaDoc

 */

4.4 其他注释

4.4.1 单行注释

单行代码注释一律使用注释界定符"//"，如：

1、 2、 3、 4、

// explain what this means if(bar > 1){        …… }

4.4.2 多行注释

       多行注释使用注释界定符"/*...*/"，如：

1、 2、 3、 4、

/*  * Here is a block comment with   * multiple lines for text comments.  */

5、其他

5.1 国际化

除了String.xml文件中可以出现非英文字符外，其他所有的Java文件，xml文件中只允许出现英文字符（中文注释除外）。

       所有Java文件，UI配置xml文件中不允许出现硬编码。字符串的国际化请写入string.xml文件，配置信息请写入config.xml文件，分辨率相关信息写入dimens.xml文件。

5.2 异常处理

使用try catch 一定要在catch语句中做好相应的处理，不能留空。在catch中可以赋默认值，做错误处理或抛出一个自己封装的异常类对象（但不能抛出RuntimeException异常）。

        使用finally这个关键字时，需要注意其中的代码执行时间点是无法确定的（无法确定

是return之前还是之后）。

5.3 引入

引用顺序：android，第三方包按字母表，java(x) 

       引用方式：一定要引全类名，不要引用整个包。 例如：

              imports foo.Bar;  //right 

              imports foo.*    //wrong 

5.4 括号

所有的复合语句必须用花括号包围，就算只有一条语句，例如：

1 2 3

if (condition) {      body();   }

5.5 TODO的引用

  当有需要在未来完成的工作时，加上TODO注释，并给出触发事件或者时间点。

1 2	// TODO: Remove this code after the UrlTable2 has been checked in.   // TODO: Change this to use a flag instead of a constant.

5.6 简化代码

l  删除无用的变量 。

l  删除无用的引用。

l  对于可以复用的部分，一定提取成共用的方法，减少代码量。

l  变量/方法命名一定要符合清晰易懂，不用太在乎长度。

l  代码完成后，进行预览，减少出错几率。

5.7 Log的使用

在调试中，应该使用Log查找问题，但在版本release之前，一定要将所有的Log关闭。

       代码要使用规范的TAG和调试开关，方便以后查找和关闭。为了方便对Log行为做全局控制，重新封装出LogUtil类。新的调用方式如下： 

1 2	private static final String TAG = "MediaScanner";  LogUtil.d(TAG,"debug info");

5.8 单位使用

  在使用单位时，如果没有特殊情况，一律采用dip和sp（字体大小单位）这两个单位。因为这两个单位是与设备分辨率无关的，能够解决在不同分辨率的设备上显示效果不同的问题。