Android代码规范指北

统一的代码风格在多人协作开发中的作用是不言而喻的,通过参考一些比较优秀的实践,这里大量参考了阿里巴巴 JAVA 开发手册,再结合了个人的思考,制定了这么一套规范,由于个人的认识是非常有限的,本规范也肯定存在很多不合理和需要补充的东西,在这里恳请大家根据自己的实践和工作中,提出一些中肯的建议和修改意见。

意义

  1. 高度有秩序的代码具有天然的美感,写代码的人心情会好很多。
  2. 减低开发人员流动带来的风险。
  3. 对于新人能更好地理解和参与到开发中。
  4. 更好的可维护性。
  5. 随之带来更好的产品质量和开发效率提升。

命名规约

  • 【强制】所有编程相关命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。
  • 【强制】所有编程相关的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。
  • 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格,必须遵从驼峰形式。

类的命名

  • 【强制】抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类命名以它要测试的类的名称开始,以 Test 结尾。
  • 【强制】相关组件类应该以组件名作为后缀以便识别。
组件 命名规则 命名举例
Activity ×××Activity MainActivity
Fragment ×××Fragment HomeFragment
Dialog ×××Dialog AlertDialog
Service ×××Service DownloadService
BroadcastReceiver ×××Receiver LoginReceiver
ContentProvider ×××Provider UserProvider
Adapter 名字+类型+Adapter ArticleListAdapter, ImageGridAdapter
AsyncTask ×××Task LoginTask
Handler 名字+所在线程+Handler HomeUIHandler, CompressWorkHandler
ViewHolder VH + 名字 VHArticle
  • 【推荐】实用工具类命名成 **Utils**Helper
  • 【推荐】EventBus 发布的事件名命名成以 Event 结尾,比如 LoginEvent
  • 【推荐】如果使用到了设计模式,建议在类名中体现出具体模式。
  • 【推荐】接口一般以大写 I 开头,回调的接口一般为 Listener 或者 Callback 结尾。

方法命名

  • 【强制】POJO 类中的任何布尔类型的变量,都不要加 is,否则部分框架解析会引起序列化错误。
    ==反例==:定义为基本数据类型 boolean isSuccess; 的属性,它的方法也是 isSuccess() ,部分Json 框架在反向解析的时候,“以为”对应的属性名称是 success,导致属性获取不到,进而抛出异常。
  • 【强制】EventBus 回调的方法必须和相关 Event 类一致,比如LoginEvent类的方法签名为: public final void onLoginEvent(LoginEvent e);
  • 【推荐】客户端逻辑大部分是基于事件驱动的,应该以on来开头,比如登录按钮的点击可以是:onLoginClick()

变量命名

  • 【强制】常量命名全部大写,单词间用下划线隔开。
  • 【强制】局部变量和一般类变量以小写字母开头。
  • 【推荐】static 类变量名称以s开头,final类变量用f开头。
  • 【推荐】组件相关的可以用【全部首字母+名字】的命名,比如 id 是 R.id.tv_login 的控件名称是:tvLogin

资源文件命名

除了 attr 和 style 资源遵循驼峰命名之外,其他资源的命名统一用小写字母+下划线的风格。

  • 【推荐】布局文件命名
布局类型 命名规则 例子
Activity activity_××× HomeActivity 对应 activity_home
Dialog dlg_××× LoginDialog 对应 dlg_login
Fragment frag_××× HomeFragment 对应 frag_home
页面标题 title_××× title_main
列表Footer footer_××× footer_article
列表Header header_××× header_article
列表的Item item_××× item_article
可重用嵌入布局 include_ ××× include_navagator
分割线 line_+颜色+大小 line_gray_1px
  • 【推荐】id命名:截取相关组件首个字母作为开头,然后以下划线作为分割。比如【TextView:tv_name】。
  • 【推荐】图片命名:【类别+名称+状态(如果有)】,根据图片的用途可以分类为图标「ic」,背景「bg」,前景「fg」(比较少用到),图片「img」(比如引导图,开机页面),如果有多个状态用同一张图,那么首选声明为 【××_selected】 。
状态 示例
正常状态 ic_login_primary
checked ic_login_checked
pressed ic_login_pressed
selected ic_login_selected
disable ic_login_disable
  • 【推荐】drawable命名
  1. xml定义图形:参考图片命名规则,在以上基础上添加辨识,比如: bg_login_shape, bg_login_vector, bg_login_shape_primary。
  2. 多个状态drawable: 命名为 【××_selector】,比如 bg_login_selector。
  • 【推荐】颜色命名
  1. 单色:命名规则为【类型+名字+状态(如果有)】,我把用到颜色的元素类型做了个归类,分别是字体「text」,背景「bg」,线「line」,还是一些常规色(比如白色,透明等),正例:text_black_primary, bg_black_selected, line_orange。
  2. 字体selector颜色:【名字 + text_selector】 ,比如 tab_item_text_selector。
  • 【推荐】尺寸命名:通用性比较强和需要适配的在 dimens.xml 中设置,一般的可以在代码中直接写。
  1. 字体大小: 【font_××】,××和设计稿保持一致的换算。
  2. 间距:组件外用【××_margin】,组件内用【××_padding】, 例子: app_left_margin。
  3. 控件大小:【宽度:××_width】,【高度:××_height】,其他【××_size】,例子: login_button_height。
  • 【推荐】其他:文字不得直接写到 java 代码和 layout 代码里面,应该抽离到相关的 strings 资源文件中;menu 和动画资源命名不需要加前缀或者后缀,能表达意图即可,因为 R.menu 或者 R.anim 已经携带了相关的信息。

代码风格

  • 【强制】大括号的使用约定。如果是大括号内为空,则简洁地写成{}即可,不需要换行;如果
    是非空代码块则:
  1. 左大括号前不换行。
  2. 左大括号后换行。
  3. 右大括号前换行。
  4. 右大括号后还有 else 等代码则不换行;表示终止右大括号后必须换行。
  • 【强制】 左括号和后一个字符之间不出现空格;同样,右括号和前一个字符之间也不出现空格; 代码块缩进 4 个空格,如果使用 tab 缩进,请设置成 1 个 tab 为 4 个空格。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
正例:
public static void main(String args[]) {
// 缩进 4 个空格
String say = "hello";
// 运算符的左右必须有一个空格
int flag = 0;
// 关键词 if 与括号之间必须有一个空格,括号内 f 与左括号,1 与右括号不需要空格
if (flag == 0) {
System.out.println(say);
}
// 左大括号前加空格且不换行;左大括号后换行
if (flag == 1) {
System.out.println("world");
// 右大括号前换行,右大括号后有 else,不用换行
} else {
System.out.println("ok");
// 右大括号做为结束,必须换行
}
}
  • 【强制】任何运算符左右必须加一个空格。

说明:运算符包括赋值运算符 =、逻辑运算符 &&、加减乘除符号、三目运行符等。

  • 【强制】方法参数在定义和传入时,多个参数逗号后边必须加空格。
  • 【强制】单行字符数限制不超过 120 个,超出需要换行,换行时,遵循如下原则:
  1. 换行时相对上一行缩进 4 个空格。
  2. 运算符与下文一起换行。
  3. 方法调用的点符号与下文一起换行。
  4. 在多个参数超长,逗号后进行换行。
  5. 在括号前不要换行,见反例。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
正例:
StringBuffer sb = new StringBuffer();
//超过 120 个字符的情况下,换行缩进 4 个空格,并且方法前的点符号一起换行
sb.append("zi").append("xin")…
.append("huang");
反例:
StringBuffer sb = new StringBuffer();
//超过 120 个字符的情况下,不要在括号前换行
sb.append("zi").append("xin")…append
("huang");
//参数很多的方法调用也超过 120 个字符,逗号后才是换行处
method(args1, args2, args3, ...
, argsX);
  • 【强制】方法参数在定义和传入时,多个参数逗号后边必须加空格。

正例:下例中实参的 “a” ,后边必须要有一个空格。method("a", "b", "c");

  • 【强制】在 if/else/for/while/do 语句中必须使用大括号,即使只有一行代码,避免使用下面的形式:if (condition) statements;

  • 【推荐】推荐尽量少用 else, if-else 的方式可以改写成:

1
2
3
4
5
if(condition){
return obj;
}
说明:如果使用要 `if-else if-else` 方式表达逻辑,【强制】请勿超过 3 层,超过请使用状态设计模式。
  • 【推荐】循环体中的语句要考量性能,以下操作尽量移至循环体外处理,如定义对象、变量,进行不必要的 try-catch 操作(这个 try-catch 是否可以移至循环体外),遍历长度的提前获取;避免使用 foreach,迭代器,尽量采用下标的形式
1
2
3
4
5
正例:
(for i=0 ;i <size; ++i)
反例:
for(int i : items)

编码规约

OOP 规约

  • 【强制】过时的类或者方法不要使用,覆盖的方法要用Override声明。这样当写错覆盖方法时可以得到编译错误提示。
  • 【强制】Object 的 equals 方法容易抛空指针异常,应使用常量或确定有值的对象来调用 equals。
  • 【强制】单例或者实用类构造方法应该声明为 private。
  • 【强制】如果用到 FastJson 来解析数据,必须在相关 getter 和 setter 方法上添加注解。
  • 【推荐】声明为 public 的方法要对参数进行校验,private 的可以不用。
  • 【推荐】当一个类有多个构造方法,或者多个同名方法,这些方法应该按顺序放置在一起,便于阅读。
  • 【推荐】 类内方法定义顺序依次是:公有方法或保护方法 > 私有方法 > getter/setter 方法。
  • 【推荐】循环体内,字符串的联接方式,使用 StringBuilder 的 append 方法进行扩展。
  • 【推荐】类成员与方法访问控制从严:
  1. 如果不允许外部直接通过 new 来创建对象,那么构造方法必须是 private。
  2. 工具类不允许有 public 或 default 构造方法。
  3. 类非 static 成员变量并且与子类共享,必须是 protected。
  4. 类非 static 成员变量并且仅在本类使用,必须是 private。
  5. 类 static 成员变量如果仅在本类使用,必须是 private。
  6. 若是 static 成员变量,必须考虑是否为 final。
  7. 类成员方法只供类内部调用,必须是 private。
  8. 类成员方法只对继承类公开,那么限制为 protected。

常量定义

  • 【强制】不允许出现任何魔法值(即未经定义的常量)直接出现在代码中。
  • 【强制】long 或者 Long 初始赋值时,必须使用大写的 L,不能是小写的 l ,小写容易跟数字 1 混淆,造成误解。
  • 【推荐】不要使用一个常量类维护所有常量,应该按常量功能进行归类,分开维护。如:缓存
    相关的常量放在类:CacheConsts 下;系统配置相关的常量放在类:ConfigConsts 下。
  • 【推荐】避免使用枚举类型,用@IntDef进行替代。

异常处理

  • 【强制】捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之,如果不想处理它,请将该异常抛给它的调用者。最外层的业务使用者,必须处理异常,将其转化为用户可以理解的内容。

    1
    2
    3
    4
    5
    6
    反例:
    void setServerPort(String value) {
    try {
    serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) { }
    }
  • 【强制】异常不要用来做流程控制,条件控制,因为异常的处理效率比条件分支低。

  • 【强制】finally 块必须对资源对象、流对象进行关闭,有异常也要做 try-catch。
  • 【强制】不能在 finally 块中使用 return,finally 块中的 return 返回后方法结束执行,不会再执行 try 块中的 return 语句。
  • 【强制】捕获异常与抛异常,必须是完全匹配,或者捕获异常是抛异常的父类。==说明==:如果预期抛的是绣球,实际接到的是铅球,就会产生意外情况。
  • 【推荐】不要偷懒直接捕获顶级异常,这样会把Runtime的异常也囊括进来,要明确每种异常出现的场景被给出相应的处理。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    反例:
    try {
    someComplicatedIOFunction(); // may throw IOException
    someComplicatedParsingFunction(); // may throw ParsingException
    someComplicatedSecurityFunction(); // may throw SecurityException
    // phew, made it all the way
    } catch (Exception e) { // I'll just catch all exceptions
    handleError(); // with one generic handler!
    }
  • 【推荐】除非有充分的理由,不要捕获 Java 类库中定义的继承自 RuntimeException 的运行时异常类,如:IndexOutOfBoundsException / NullPointerException,这类异常由程序员预检查来规避,保证程序健壮性。

代码注释

  • 【强制】类、类属性、类方法的注释必须使用 javadoc 规范,使用/*内容/格式,不得使用//xxx 方式。
  • 【强制】所有的抽象方法(包括接口中的方法)必须要用 javadoc 注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。
  • 【强制】所有的类都必须添加创建者信息。
  • 【强制】对那些临时性的、短期的、够棒但不完美的代码,请使用TODO注释。

    1
    // TODO: Change this to use a flag instead of a constant.
  • 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/ /注释,注意与代码对齐。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    void method(){
    // 打个招呼
    sayHello();
    /*
    这里保持移动,
    并不断对步数加1
    */
    keepMove();
    }
  • 【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的一
    个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。

Android 实践

  • 【强制】避免对同个 View 进行多次查找,应该缓存起来,比如列表中使用的 ViewHolder 模式。
1
2
3
反例:
view.findViewById(R.id.iv_toolbar_right).setOnClickListener(this);
view.findViewById(R.id.iv_toolbar_right).setEnabled(true);
  • 【强制】不要使用 System.out.println() ,printf() 打印日志。
  • 【强制】调试日志要有个开关,在正式发布的时候不能出现应用日志打印。
  • 【强制】读文件,数据库,网络请求等一些耗时操作必须在异步线程中执行。
  • 【强制】不能粗暴的把 Activity, Service 对象或者一些比较重的对象直接声明为 static 变量,如果必须这么做,请注意它们的生命周期变化。
  • 【强制】每引入一个第三方库,要检查是否加入相关的混淆规则。
  • 【强制】自定义属性动画 (ObjectAnimator) 的 getter 和 setter 方法时要注意防止混淆。
  • 【强制】在 (Activity,Fragment) 组件退出时要保证相关资源得到释放,比如 EventBus 订阅的事件,注册的广播,轮播任务等。
  • 【强制】对于Api Level大于等于23的设备要进行运行时权限检查。
  • 【推荐】在使用 Thread,Handler,AsyncTask,Timer,耗时的匿名回调类,内部类时,考虑声明成静态的内部类,并且弱引用或者软引用来处理相关的大对象,并且要注意生命周期的变化,避免出现内存泄漏问题。
  • 【推荐】利用 TextView 的drawableLeft等来减少 ImageView 的使用。
  • 【推荐】通过使用 RelativeLayout 或者 ConstraintLayout 来减少布局的层次。
  • 【推荐】在 findViewById 尽可能选取一个比较近的父节点来减少查找时间。
  • 【推荐】Bundle 中的常量 Key 值统一在一个文件中,而不是直接在 Activity 或者 Fragment 中,比如 BundleKeys 文件中。
  • 【推荐】可滑动列表复用的 ViewHolder 对象中,对于一些事件对象应该尽可能地复用。
  • 【推荐】对隐式 Intent 的运行时调用 resolveActivity 进行检查保护。
  • 【推荐】使用 NotificationCompat 兼容包来处理消息通知。
  • 【推荐】延迟创建没有用到的对象,比如 Adapter 的列表对象,应该在请求数据取到之后再去创建,而不是提前创建好。
  • 【推荐】使用 ArrayMap,Sparse×× 系列对象来减少内存消耗和避免AutoBoxing。
  • 【推荐】更新列表局部数据避免粗暴地调用 Adapter.notifyDataSetChanged,应该只更新变化的部分。
  • 【推荐】用 @Nullable, @NonNull, @IdRes, @MainThread 等Support Annotations注解来增强代码的编译期检查和可读性。
  • 【参考】如果不用getColor(int id, Theme theme)等相关方法,至少使用 ContextCompat 来获取相关 Color 或者图片资源。
  • 【参考】尽可能通过 Fragment 来实现视图层,Activity 只是负责嵌入和管理。
  • 【参考】通过 Picasso,Glide 等开源组件去加载和缓存你的图片。

资料参考

  1. 阿里巴巴 JAVA 开发手册
  2. Android Code Style Rules
  3. 常见的八种导致 APP 内存泄漏的问题
  4. Android开发最佳实践
  5. Android Support Annotations
坚持原创分享,您的支持将鼓励我继续创作!