安卓开发规范__Android编码规范

安卓开发规范
编写目的
为了使项目文档组织有序，方便项目组成员协调开发工作，便于后期开发人员理解和维护代码，公司的android开发项目应该有一套命名规范，小组人员在编写代码时应该遵循这些规范，使用有意义的字符书写代码中得类型、变量，形成良好的编码风格。

简单描述
工程文件编码格式：UTF-8
包结构
src的目录结构
com.hy.prss.mobile.android.constant
例如：Server_Config.java
描述：包下的所有类里只能装常量，常量格式public static final xxx XXX = xxx;
R.id.xxx类似的资源文件不能定义在arrays里，定义在常量包里方便调用
com.hy.prss.mobile.android.widget
例如：IconTextListView.java，PictureDialog.java
描述：包下的所有类里只能是自定义控件或自定义dialog
com.hy.prss.mobile.android.entity
例如：User.java
描述：包下的所有类里只能是属性变量+get和set方法
com.hy.prss.mobile.android.activity
例如：MainActivity.java
MyActivity是所有的Activity的父类，对Activity的统一的处理在MyActivity实现，如：对顶部标题栏的显示和底部标题栏的显示
Activity的作用: 加载layout, 初始化控件，设置监听，处理监听事件
描述：所有活动的集合
com.hy.prss.mobile.android.service
例如：UserManager.java
描述：业务层
com.hy.prss.mobile.android.dao
例如：SqlDBHelper.java
描述：数据访问
com.hy.prss.mobile.android.util
例如：XmlUtil.java
描述：所有的零碎功能
包括处理XmlUtil, JsonUtil，SharedPreferencesUtil, DBUtil，FileUtil，HttpUtil，SocketUtil，StringUtil, DeviceUtil
com.hy.prss.mobile.android.app
例如：MyService.java
描述：
存放Broadcast，service, application
所有的Service继承MyService
服务：
●用在不需要界面时，还需要长时间在后台运行的地方
广播：
●用来接收系统
●广播用于处理后台服务与前台界面的交互
com.hy.prss.mobile.android.test
例如：
描述：
junit test模块测试
values的目录结构
代码规范
java代码命名规范
类名、接口命名规则
类和接口的名称应该是一个名词，与设计文档保持一致；
采用大小写混和的方式，每个单词的首字母大写；
命名使用完整单词，禁止使用中文全拼，如使用缩写词必须添加注释（除非该缩写词被广泛的使用，如URL、HTML）；
例如
class UserTest;//各单词首字母大写
interface IUserTest;//接口以大写I开头
abstract class AbsUserTest; //抽象类以Abs开头
方法函数命名规则
方法名应该是动词/动名词，采用大小写混和方式，第一个单词首字母小写，其后单词的首字线大写。

例如
run()
runFase()
变量命名规则
变量命名采用大小写混和的方式，第一个单词首字母小写，其后单词的首字母大写。

变量名应简短有意义；
尽量避免单个字符的变量名（临时变量除外）；
所有变量要显式的赋值；
静态变量命名采用全大写字母，中间用下划线分隔。

例如
int total = 0;
String name = null;
Button bnStart = new Button();
static int MAX_CODE_LINE = 200;
资源文件代码命名规范
命名文件名
因为该文件名不识别大写字符，所有单词间以下划线分割
例如：activity_main
命名内部属性名
参考变量命名规则
例如:
bnStart
styleDialog
widget缩写对应表
因为widget比较常用所以特用缩写代替
缩写对应如下：
TextView tv EditText et
WebView wv ImageView iv
VideoView vv MediaController mc
ListView lv GridView gv
Gallery gly Button btn
ImageButton ib CheckBox cb
RadioButton rb SeekBar sb
ProgressBar pb Spinner spr
SearchView sv AnalogClock ac
TimePicker tp DatePicker dp
代码注释
生成api的方法
1.选择工程，鼠标右键菜单Export ，选择Java 下面的Javadoc ，点”next”
按钮
2.Javadoc command 里选javadoc.exe 的目录，如：C:\Program
Files\Java\jdk1.6.0_10\bin\javadoc.exe
3.选择生成到Javadoc 文档中的内容( 一般选public 或protected) ，选
存放目录( 默认即可) ，next下一步,此页全默认即可，再next 下一步。

4.如果项目采用的是UTF －8 的编码，一定要在这一页的Extra
Javadoc options 中加” -encoding UTF-8 -charset UTF-8 〃。

否则生成的网页中文注释都是乱码。

点Finish 完成
5.所有的代码注释都会被自动加入api中，所以为了让他人看懂所写代码，
在编写程序代码的时候尽量加全所有可以被加入到api中的注释
java代码注释
设置方法
设置注释模板的入口：Window->Preference->Java->Code
Style->Code Template 然后展开Comments节点，对个个节点进行设
置
类说明注释
该注释一般位于package/import语句之前，class描述之前。

要求至少
写出内容说明、创建者、创建时间和特别注意事项等内容。

例如
/**
* 对类的说明
* @author 张三
* @time ${date}${time}
* @version
*/
方法说明注释
对每个方法都应有适当的说明，位于方法声明之前，包括：说明、参数
说明、异常说明、返回值说明和特别说明等
例如
/**
* 对方法的说明
* @param id 查询用ID
* @return User实体类
*/
方法体内代码的注释
块的注释
/***************** 说明 ******************/
对单行的注释
// 说明
对多行的注释
/*
* 说明1
* 说明2
*/
例如
/***************** 是否是超级管理员 ******************/
Private Boolean isAdmin = false;
/*
* isAdmin == true处理
* false不处理
*/
If(isAdmin){
// 设置用户id
userId = “111”;
}
资源文件代码注释
块的注释
<!-- 说明 -->
<skip />
变量注释
<!-- 说明 -->
Android编码规范
文件组织方式
考虑到开发效率，前期将所有代码在一个工程中开发，但同时也希望保持将代码拆分成几个工程的可能性，基于这一考虑，决定在工程下面新建若干个并行的代码目录，如图所示：
每个目录所对应的代码
face Avatar视频通话
contacts 联系人app
public 公用接口、库
messages 消息app
service 服务daemon
考虑到开发效率，在IDE中，可以把所有这些目录做为source folder一起开发、调试。

在实际开发中，各模块的代码应保持独立，除都需要依赖公用接口public外，其余各模块应能独立编译通过。

各模块的独立性可通过daily build脚本进行验证。

考虑到build system的支持问题，含有中文的源文件须使用UTF-8编码。

包名规范
工程文件夹名
AvatarMessenger
工程包名
com.tencent.avatar
包名
UI界面
com.tencent.avatar.profile
com.tencent.avatar.contacts
com.tencent.avatar.messages
com.tencent.avatar.face
服务接口
com.tencent.avatar.service.aidl
com.tencent.avatar.service.data
服务实现
com.tencent.avatar.service.action
com.tencent.avatar.service.profile
com.tencent.avatar.service.contacts
com.tencent.avatar.service.messages
com.tencent.avatar.service.face
网络协议层
com.tencent.im.api
公用工具类
com.tencent.avatar.utils
编码规范
项目的编码规范遵守Android和Java的编码规范。

具体可查看
/source/code-style.html
建议完整阅读完此文档，此文当中包含很多有用信息。

命名
变量命名
非公有，非静态的变量以m开头
静态变量以s开头
其它变量名以小写字母开头
常量（public static final）的风格为ALL_CAPS_WITH_UNDERSCORES 如：
public class MyClass {
public static final int SOME_CONSTANT = 42;
public int publicField;
private static MyClass sSingleton;
int mPackagePrivate;
private int mPrivate;
protected int mProtected;
}
与NDK相关的Java代码因为需要与native代码对应，可不遵守此规则
类、接口命名
类名应当是名词，每个单词首字母大写。

前面不需要增加C。

接口应当象类名那样使用首字母大写，但名字前面需要加上I，以表明此名字为接口。

方法应当是动词，首个单词的首字母小写，随后的单词首字母大写。

对于常用的技术缩写词，应把它当成一个普通单词对待，如createHttpRequest、createUiNode、readFromDb。

回调接口命名
对于实现Observer模式的接口，回调接口名称以Observer结尾。

与Android相关的接口以Listener结尾，从NDK回调回Java的代码函数可以Callback结尾。

异步方法命名
对于异步调用的函数须在前面加小a，表明此函数为异步调用。

对于其它类型的函数，也可适当增加前缀，如ntf。

错误处理规范
各层之间的接口的同步方法调用的错误返回应都通过throw exception的方式实现。

除在极少的情况，如需在最高层捕获generic exception之外，任何时候都不应该捕捉generic exception。

若系统中提供的Exception子类符合要求，应优先使用系统的Exception子类，而不应创建自己的Exception类。

若需要创建自己的Exception类，应从统一的基类继承，如MTTException （此类包含什么信息需要再讨论）。

Log使用规范
使用
项目中使用自定义的Log输出函数，此函数的参数与Android的Log函数一致，可根据常量控制是使用标准Log输出，还是写入到文件。

如下所示：
private static final String TAG = "VideoManager";
输出时使用：
ALog.d(TAG, "DELETE VIDEO INDEX:" + index);
根据Log的严重程度可分别使用ALog.v、ALog.d、ALog.i、ALog.w、ALog.e。

这样在使用IDE调试的时候可以方便的过滤信息。

条件编译
与C/C++不同，Java不支持预编译，为了使得最终编出的release版本不包含Log信息，一般使用以下的做法。

先定义独立的DebugFlags类
public class DebugFlags {
public static final boolean PRINT_VCL = true;
public static final boolean PRINT_SERVICE_MGR = true;
public static final boolean ASSERT_ENABLED = true;
}
在需要输出Log的时候，使用如下的方式
if (DebugFlags.PRINT_VCL) {
Log.i(TAG, "connection resumed");
}
因为所定义的常量都是final类型的，所以若把这些常量设置为false则编译器会优化，移除与输出Log相关的代码。

SDK版本号
项目的开发基于SDK Level 9(Android 2.3.1)，minSdk设为Level 7(Android 2.1)。

注释
文件头注释
文件开头注释，使用以下规范
/*
Name : PrintLog.java
Version : 0.0.1
Copyright : Copyright (c) Tencent Inc. All rights reserved. Description : provide printing log function.
print log to logcat.
annex the class name and function name which call it. */
用Eclipse自动生成文件头注释
Eclipse同样可以很方便的自动生成文件注释，要使用，先需要导入相应的配置文件，步骤如下。

在Eclipse中，选择菜单Window->Preferences
选择Java->Code Style->Code Templates，点击Import按钮，选择附带的tr-codetemplates.xml 文件，按确定。

当需要新增加类或接口时，使用菜单File->New->Class，输入相应的信息，并选中对话框最底下的Generate comments，按Finish即可。

生成的文件如下图所示
类和方法注释
对于类和方法，不要求注释。

但建议各层之间的接口方法，使用注释。

在注释的时候，使用文档注释，方便javadoc生成文档。

/**
* Returns an Image object that can then be painted on the screen. * The url argument must specify an absolute {@link URL}. The name * argument is a specifier that is relative to the url argument.
*
* @param url an absolute URL giving the base location of the image * @param name the location of the image, relative to the url argument * @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
retur n null;
}
}
Tips
若要添加javadoc注释，只要将光标置于需要添加的代码之中，使用菜单Source -> Generate Element Comment，或使用快捷键Alt+Shift+J，eclipse会自动添加相应注释框架。

风格规范
Eclipse提供了很好的Code style formatter，我们可以用这一工具来保证我们的代码风格。

只需要大家使用统一的配置Profile即可。

附带的tr-android-formatting.xml为我们组所使用的代码风格配置文件。

导入Eclipse方法
在Eclipse里，选中菜单Window -> Preferences
选择Java->Code Style->Formatter，点击Import按钮，选择tr-android-formatting.xml文件。

使用方法
选中想要格式化的代码，使用菜单Source->Format，或者快捷键Ctrl+Shift+F。

以下的风格要求都可以通过使用这一工具得到实现：
●缩进（使用4个空格代替Tab）
●花括号位置（与代码同一行）
●表达式、语句间的空格
●语句间的空白行
Import顺序
同样，Eclipse提供了很方便的工具来管理import的顺序，导入android的设置
在Eclipse里，选中菜单Window -> Preferences
选择Java->Code Style->Organize Imports，点击Import
选择android.importorder
使用方法
任何时候，选择菜单Source->Organize Imports或快捷键Ctrl+Shift+O即可删除不必要的import，同时对import进行排序。

除Java标准库（java.util.*, java.io.*等）和单元测试代码（junit.framework.*）外，任何时候都不要在import中使用通配符，而应该显示的表明要import的类，如import foo.Bar。

Tips:
当Eclipse提示某个类需要imports时，可以将光标置于这个类中，选择菜单Source->Add Imports或者是快捷键Ctrl+Shift+M，Eclipse会自动加入相关的import语句。