Android编程规范

    转载请注明出处：http://blog.csdn.net/zhaokaiqiang1992

1.概述

1.1目的与概述

本文提供一整套编写高效可靠的android代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。而且，通过遵循这些程序设计标准，你作为一个 Java 或者android 软件开发者的生产效率会有显著提高。经验证明，若从一开始就花时间编写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。

1.2适用对象

1)       Android开发工程师

2)       Java开发工程师

1.3参考资料

Ø  RUP2000中文版的《Java编程指南》

Ø  Draft JavaCoding Standard     Doug Lea

Ø  Javasoft codingstandards

Ø  TheInfospheres Java Coding Standard

1.4整体原则

原则(优先级从上到下递减)

约定

便于阅读

缩进

适当地增加括号

折行

行宽限制

与工具集成

对JavaDoc的注释支持

Eclipse的模板文件及配置

便于调试

一行一条语句

便于写作

注释与语句不同行

减少重复

同样的内容不在多处重复

2.Android编程规范

2.1命名规范

2.1.1命名的基本原则

在面向对象编程中，对于类，对象，方法，变量等方面的命名是非常有技巧的。比如，大小写的区分，使用不同字母开头等等。但究其本，追其源，在为一个资源命命名的时候，应该本着描述性和唯一性这两大特征来命名，才能保证资源之间不冲突，并且每一个都便于记忆。

命名的一个基本原则是：使名称足够长以便有一定的意义，并且足够短以避免冗长。

2.1.2通用的命名约定

采用该领域的术语。如果用户称他们的“客户” (clients) 为“顾客” (customer)，那么就采用术语 Customer 来命名这个类，而不用 Client。

 注意大小写。常量的字母全部大写，单词之间用一个下划线字符“_”进行分隔。除常量外的命名采用大小写混合，提高名字的可读性。一般变量采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。这个命名规则也就是通常意义上的驼峰标识命名法。

使用可以准确说明的英文描述符。例如，采用类似firstName或CorporateCustomer这样的名字。虽然象 x1，y1这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。

下面是通用的命名规范

标识符类型

命名规则

Examples

Packages

每一个包的名称总是小写，规则采用公司域名倒置，然后加上包的功能名。

com.baidu.map

Classes

类名必须是名词，首字母大写，采用驼峰命名法。类名应该简单清晰。

class User;
class UpdateInfo;

Interfaces

同类名规则。

interface RasterDelegate;

Methods

方法应该是动词，或以动词开始的动宾结构短语，首字母小写，采用驼峰命名法。

runFast();
getBackground();

Variables

变量名应该短而准确并便于记忆。首字母小写，采用驼峰命名法。除了临时使用的如循环变量等以外，不要使用单字符的变量名。对于使用单字符的临时变量名，建议循环变量名用i,j,k，n表示整数。

Int  i;

char c;

float myWidth;

Constants

全部大写，单词之间用下划线分隔。

static final int MIN_WIDTH = 4;

2.1.3非强制的命名规范

类型

规则

例

抽象类

以Abstract开始

AbstractDjinn, AbstractCat, AbstractClass, AbstractPlayer

Factory类

以Factory结束

DjinnFactory, CatFactory, ClassFactory, PlayerFactor

Exception

以Exception结束

DjinnException, CatException, ClassException, PlayerException

Interface

以Interface结束或加-able后缀

DjinnInterface, CatInterface, Runnable, RemoteLoadable

2.2格式规范

2.2.1括号

在表达式、方法调用及方法声明中圆括号“(”后及“)”前不应该有空格。

2.2.2缩进

一种提高代码可读性的方法是给代码分段，换句话说，就是在代码块内让代码缩进。所有在括号{和}之内的代码，构成一个块。基本思想是，块内的代码都应统一地缩进去一个单位。

同级之间应该在同一个缩进位置。在下一级与上一级之间需要缩进。缩进单位默认为4个空格，即一个Tab键的距离。

2.2.3空白行

在代码中加入几个空行，将代码分为一些小的、容易理解的部分，可以使它更加可读。建议采用一个空行来分隔代码的逻辑组，例如控制结构；采用两个空行来分隔方法定义。没有空白的代码很难读，很难理解。

下列情况下，一般需要写入空白行：

Ø  包和引入之间加一个空行

Ø  不同可见性的变量定义之间加一个空行

Ø  方法定义之间加一个空行

Ø  不同可见性的方法组定义之间多加一个空行

2.2.4空格

Ø 关键字与其后紧挨的括号之间应有一个空格进行分隔。

Ø 参数列表的逗号之后应有一个空格进行分隔。

Ø 大括号开始之前应有一个空格进行分隔。

Ø 所有的二元操作符的前后均应有一个空格，二元操作符的例子有加号，除号，等于符号，赋值符号等。

Ø for的每一个语句之间应有空格，即for (expr1; expr2; expr3) 或者 for(expr1 : expr2)

Ø 强制类型转换的括号之后应有一个空格。

虽然添加空格的情况很多，但是不要担心，如果你是使用Eclipse开发的话，使用Shift+Ctrl+F快捷键，可以把代码快速格式化。

2.2.5行宽

行宽不得超过最大行宽，超过最大行宽就需要折行，最大行宽为80。

行宽超过最大行宽往往需要用横向滚动条，影响阅读，而最大行宽之内的字符数在大多数阅读器中均能方便地进行阅读及打印。

2.3注释规范

除Get,Set，构造析构等极其明白易懂的函数外，函数应当加上注释。个别函数参数或返回值有约定时，应给出注释说明。

函数体超过20行，应当在核心思想处给出注释。

2.3.1注释风格

注释语句类型

用法

示例

文档注释

在接口、类、方法和字段声明之前紧靠它们的位置用文档注释进行说明。文档注释由javadoc处理，为一个类生成外部注释文档。

/**

Customer（顾客）顾客是指作为我们的服务及产品的销售对象的任何个人或组织。

@author S.W. Ambler

*/

C语言风格注释

采用 C 语言风格的注释语句将无用的代码注释掉。保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。

/*

这部分代码已被它前面的代码替代，所以于 1999 年6 月 4 日被 B. Gustafsson注释掉。如果两年之后仍未用这些代码，将其删除。

. . . （源代码）

*/

单行注释

在方法内部采用单行注释语句对业务逻辑、代码片段和临时变量声明进行说明。

// 因为让利活动

// 发货单 5% 的折扣。

2.3.2常见Javadoc注释标记

标记

用于

目的

@author name

类、

接口

说明特定某一段程序代码的作者。

@deprecated

类、

方法

说明该类的应用程序编程接口 (API) 已被废弃，因此应不再使用。

@exception name description

方法

说明由方法发出的异常。一个异常采用一个标记，并要给出异常的完整类名。

@param name description

方法

用来说明传递给一个方法的参数，其中包括参数的类型/类和用法。每个参数各有一个标记。

@return description

方法

若方法有返回值，对该返回值进行说明。

@see ClassName

类、接口、方法、字段

在文档中生成指向特定类的超文本链接。可以并且应该采用完全合法的类名。

@see ClassName#memberfunctionName

类、接口、方法、字段

在文档中生成指向特定方法的超文本链接。可以并且应该采用完全合法的类名。

@version text

类、接口

说明特定一段代码的版本信息。

2.3.3通用注释规范

       在一个类文件中，注释主要分为头文件注释、类注释、变量注释、方法注释，下面对各种注释方式进行详细介绍。

Ø  头文件注释。每个Java源文件必须以一个C语言风格的注释开始，该注释包括文件名，版本信息，日期，作者及版权声明。

一个可用的模版格式如下：

/*

* Copyright (c) 2014, 青岛司通科技有限公司 All rights reserved.

* File Name：${file_name}

* Version：V1.0

* Author：zhaokaiqiang

* Date：${date}

*/

设置方法如下图所示

Ø  类注释。类注释主要对类的功能，创建时间，作者进行说明。一个可用的模版如下

/**

* @ClassName: ${package_name}.${type_name}

* @Description:

* @author zhaokaiqiang

* @date ${date} ${time}

*

*/

设置方法与头文件注释类似

Ø  方法注释。方法注释主要对一个方法的主要功能，返回值，异常信息进行描述。一个可用的模版如下

/**

* @Description: ${todo}

* @param

* @return ${return_type}

* @throws

*/

Ø  字段注释。变量注释主要对变量的作用进行描述。可以使用单行注释。

Ø  其他注释。其他注释包括复杂业务逻辑的注释，for/while循环控制结构的注释等其他任何通过注释可以增加代码可读性的地方。

2.4开发规范

2.4.1控件命名规范

TextView ：tv_+描述

Button ：btn_+描述

ImageButton ：imgBtn_+描述

ImageView ：imgView_+描述

CheckBox ：chk_+描述

RadioButton ：rdoBtn_+描述

AnalogClock ：anaClk_+描述

DigitalClock ：DgtClk_+描述

DatePicker ：dtPk_+描述

TimePicker ：tmPk _+描述

ToggleButton ：tglBtn_+描述

EditText：et_+描述

ProgressBar：pb_+描述

SeekBar：skBar _+描述

AutoCompleteTextView：autoTv_+描述

MultiAutoCompleteTextView mlAutoTv_+描述

ZoomControls：zmCtrl_+描述

Include：ind_+描述

VideoView：vdoVi_+描述

WebView：webView_+描述

RatingBar：ratBar_+描述

Tab：tab_+描述

Spinner：spn_+描述

MapView: mapVi_+描述

ScrollView：sclVi_+描述

TextSwitcher：tvSwt_+描述

Gallery：gal_+描述

ImageSwitcher：imgSwt_+描述

GridView：gv_+描述

ListView：lv_+描述

控件说明如下：

•    TextView - 文本显示控件

•    Button - 按钮控件

•    ImageButton - 图片按钮控件

•    ImageView - 图片显示控件

•    CheckBox - 复选框控件

•    RadioButton - 单选框控件

•    AnalogClock - 钟表（带表盘）控件

•    DigitalClock - 电子表控件

•    DatePicker - 日期选择控件

•    TimePicker - 时间选择控件

•    ToggleButton - 双状态按钮控件

•    EditText - 可编辑文本控件

•    ProgressBar - 进度条控件

•    SeekBar - 可拖动的进度条控件

•    AutoCompleteTextView - 支持自动完成功能的可编辑文本控件

•    MultiAutoCompleteTextView - 支持自动完成功能的可编辑文本控件，允许输入多值（多值之间会自动地用指定的分隔符分开）

•    ZoomControls - 放大/缩小按钮控件

•    Include - 整合控件

•    VideoView - 视频播放控件

•    WebView - 浏览器控件

•    RatingBar - 评分控件

•    Tab - 选项卡控件

•    Spinner - 下拉框控件

•    Chronometer - 计时器控件

•    ScrollView - 滚动条控件

•    TextSwitcher - 文字转换器控件（改变文字时增加一些动画效果）

•    Gallery –画廊控件

•    ImageSwitcher - 图片转换器控件（改变图片时增加一些动画效果）

•    GridView - 网格控件

•    ListView - 列表控件

•    ExpandableList - 支持展开/收缩功能的列表控件

2.4.2单位使用规范

       控件长宽采用dp作为统一的衡量单位，字体使用sp作为统一衡量单位。

2.4.3切图命名规范

       具体命名规范，请看《Android切图规范及命名规则》文档。

2.4.4资源文件夹res下的规范

       在res资源目录下，应该至少包含下面的目录结构

       其中，各个版本的drawable中存放的内容如下

Ø  drawable      存放使用xml文件实现的各种selector按下效果

Ø  drawable-hdpi     存放480*800，480*854像素的图片

Ø  drawable-ldpi      存放240*320像素的图片，现在基本废弃

Ø  drawable-mdpi   存放320*480像素的图片，现在基本废弃

Ø  drawable-xhdpi   存放720*1280像素及以上的图片

Ø  drawable-xxhdpi 暂时只放144px的图标

3.最佳实践

本节描述在编码中的最佳实践，这些实践并不强制使用，但它们是由技术人员使用多年并被证明行之有效的方法。当然，这些实践的使用有些可能是不适用的，因此需要根据实际情况酌情使用。

3.1先写注释再写代码

写代码注释的最好方法是在写代码之前就写注释。这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗漏注释。另一种方法是边写代码边写注释。因为注释可以使代码更易理解，所以在程序开发的过程中，也可以利用这一点。如果打算花些时间写注释，那么至少你应从这个过程中获得些什么。

3.2在文档中加入HEML标记

在文档注释中加入HTML标记，可使最后生成的技术文档的格式丰富而变得更有表现力，因此强烈推荐采用在文档注释中加入HTML标记的做法。但是，由于Javadoc可在多种媒体中发布，可能会在一个不支持HTML的媒体上进行发布，因此在文档注释中加入HTML标记也会带来一些潜在的问题，但在当前环境中不会出现问题。

3.3尽量不要使用公共的类变量

因为直接暴露类变量会影响类对自身结构的控制。另外因为外部可以直接修改类变量，类的方法也不能对暴露的类变量作任何假设。另一方面从效率上来讲，由于一些现代的虚拟机会自动优化直接访问类变量的getXXX，setXXX类型的函数，效率上也不会产生问题。

3.4对于对象的比较慎用==,使用Object.equals()方法

多数情况下equals才能工作正常。

3.5可移植性

Ø  尽量不要使用已经被标为不赞成使用的类或方法。

Ø  如果需要换行的话，尽量用println来代替,在字符串中使用"\n"。

Ø  用separator()方法代替路径中的”/”或”\”。

Ø  用pathSeptarator()方法代替路径中的” : ”或” ;”。

3.6错误和异常信息的处理

通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。

       通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常，包括异常发生的时刻。不要使用异常实现来控制程序流程结构。