Android开发代码规范总结

前言

为了有利于项目维护、增强代码可读性、提升 Code Review 效率以及规范团队安卓开发，故提出以下安卓开发规范。

一、Android Studio 规范

1. 尽量使用最新的稳定版 Android Studio 进行开发；
2. 编码格式统一为 UTF-8；
3. 编辑完 .java、.kt、.xml 等文件后一定要 格式化，格式化，格式化（如果团队有公共的样式包，那就遵循它，否则统一使用 AS 默认模板即可，Mac 下可以使用快捷键 cmd + alt + L 进行代码格式化，Window 下可以使用快捷键 ctrl + alt + L 进行代码格式化）；
4. 删除多余的 import，减少警告出现，Mac 下可以使用快捷键 ctrl + alt + O 进行 import 优化，Window 下可以使用快捷键 ctrl + alt + O 进行 import 优化；

二、Kotlin命名

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。正确的英文拼写和语法可以让阅读者易于理解，避免歧义。

注意：即使纯拼音命名方式也要避免采用。但 alibaba、taobao、youku、hangzhou 等国际通用的名称，可视同英文。

2.1 包名

包名全部小写，连续的单词只是简单地连接起来，不使用下划线，采用反域名命名规则，全部使用小写字母。一级包名是顶级域名，通常为 com、edu、gov、net、org 等，二级包名为公司名，三级包名根据应用进行命名，后面就是对包名的划分了，关于包名的划分，推荐采用 PBF（按功能分包 Package By Feature）。

// BAD
com.RayWenderlich.funky_widget
// GOOD
com.raywenderlich.funkywidget

2.2 类名

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

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

测试类的命名以它要测试的类的名称开始，以 Test 结束。例如：HashTest 或 HashIntegrationTest。

接口（interface）：命名规则与类一样采用大驼峰命名法，多以 able 或 ible 结尾，如 interface Runnable、interface Accessible；或者以 I 为前缀。

类	描述	示例
Activity 类	以Activity 为后缀标识	欢迎页面类 WelcomeActivity
Adapter 类	以Adapter 为后缀标识	新闻详情适配器 NewsDetailAdapter
解析类	以Parser 为后缀标识	首页解析类 HomePosterParser
工具方法类	以Util、Tool、Manager 为后缀标识	线程池管理类：ThreadPoolManager，日志工具类：LogUtil，网络请求工具类：HttpTool
数据库类	以 DBHelper 后缀标识	新闻数据库：NewsDBHelper
Service 类	以 Service 为后缀标识	时间服务 TimeService 用户组件服务IUserService
BroadcastReceiver 类	以 Receiver 为后缀标识	推送接收 JPushReceiver
ContentProvider 类	以 Provider 为后缀标识	ShareProvider
自定义的共享基础类	以 Base 为前缀	BaseActivity, BaseFragment

上面提到工具类以 Util 和 Tool 为后缀，那么 Util 和 Tool 的区别是什么？Util 是无业务逻辑的，Tool 是有业务逻辑的。比如 HttpUtil 只是包含了基本网络请求，而 HttpTool 中包含了项目的一些配置，如在每个请求增加 token 。也可以这么说，HttpUtil 可以跨项目使用，而 HttpTool 只能在该项目中使用。

2.3 方法名

方法名都以 lowerCamelCase 风格编写。

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

方法	说明
initXX()	初始化相关方法，如初始化布局 initView()
isXX(), checkXX()	方法返回值为 boolean 型
handleXX(), processXX()	对数据进行处理的方法
displayXX(), showXX()	弹出提示框和提示信息
resetXX()	重置数据
clearXX()	清除数据
drawXX()	绘制数据或效果相关的
setXX()	设置某个属性值
getXX()	返回某个值或单个对象
listXX()	返回多个对象
countXX()	返回统计值
saveXX(), insertXX()	保存或插入数据
removeXX(), deleteXX()	移除数据或者视图等，如 removeView()
updateXX()	更新数据

2.4 常量名

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

每个常量都是一个 static final 字段，但不是所有 static final 字段都是常量。在决定一个字段是否是一个常量时，得考虑它是否真的感觉像是一个常量。例如，如果观测任何一个该实例的状态是可变的，则它几乎肯定不会是一个常量。只是永远不打算改变的对象一般是不够的，它要真的一直不变才能将它示为常量。

// Constants
static final int NUMBER = 5;
static final ImmutableListNAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final SetmutableCollection = new HashSet();
static final ImmutableSetmutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

Android SDK 中的很多类都用到了键值对函数，比如 SharedPreferences、Bundle、Intent，所以，即便是一个小应用，我们最终也不得不编写大量的字符串常量。

当时用到这些类的时候，我们 必须 将它们的键定义为 const val 字段，并遵循以下指示作为前缀。

类	字段名前缀
SharedPreferences	PREF_
Bundle	BUNDLE_
Fragment Arguments	ARGUMENT_
Intent Extra	EXTRA_
Intent Action	ACTION_
save instance state	SAVED_

虽然 Fragment.getArguments() 和 onSaveInstanceState 也是使用的 Bundle ，但为了区分不同的使用场景，所以定义了不同的前缀。

2.5 非常量字段名

非常量字段名以 lowerCamelCase 风格的基础上改造为如下风格：基本结构为 scope{Type0}VariableName{Type1}、type0VariableName{Type1}、variableName{Type1}。

说明：{} 中的内容为可选。

注意：所有的 VO（值对象）统一采用标准的 lowerCamelCase 风格编写，所有的 DTO（数据传输对象）就按照接口文档中定义的字段名编写。

2.5.1 scope（范围）

非公有，非静态字段命名以 m 开头。

静态字段命名以 s 开头。

其他字段以小写字母开头。

例如：

public class MyClass {
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

使用 1 个字符前缀来表示作用范围，1 个字符的前缀必须小写，前缀后面是由表意性强的一个单词或多个单词组成的名字，而且每个单词的首写字母大写，其它字母小写，这样保证了对变量名能够进行正确的断句。

通过IDE 自动生成get 、set 和构造函数的时候，这个没有任何实际意义的m前缀会被包含到变量名称当中去，显得很low也很容易影响可读性。在 AS 中，Settings -> Editor -> Code Style -> Java -> Code Generation 中，Field Name prefix 设置 m，Static Field Name prefix 设置 s。这样 AS 就可以识别了，自动生成方法的时候会去掉 s 或 m。

2.5.2 Type0（控件类型）

考虑到 Android 众多的 UI 控件，为避免控件和普通成员变量混淆以及更好地表达意思，所有用来表示控件的成员变量统一加上控件缩写作为前缀（具体见附录 [UI 控件缩写表](#UI 控件缩写表)）。

例如：mIvAvatar、rvBooks、flContainer。

2.5.3 VariableName（变量名）

变量名中可能会出现量词，我们需要创建统一的量词，它们更容易理解，也更容易搜索。

例如：mFirstBook、mPreBook、curBook。

量词列表	量词后缀说明
First	一组变量中的第一个
Last	一组变量中的最后一个
Next	一组变量中的下一个
Pre	一组变量中的上一个
Cur	一组变量中的当前变量

2.5.4 Type1（数据类型）

对于表示集合或者数组的非常量字段名，我们可以添加后缀来增强字段的可读性，比如：

集合添加如下后缀：List、Map、Set。

数组添加如下后缀：Arr。

例如：mIvAvatarList、userArr、firstNameSet。

注意：如果数据类型不确定的话，比如表示的是很多书，那么使用其复数形式来表示也可，例如 mBooks。

2.6 参数名

参数名以 lowerCamelCase 风格编写。

2.7 局部变量名

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

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

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

2.8 临时变量

临时变量通常被取名为 i、j、k、m 和 n，它们一般用于整型；c、d、e，它们一般用于字符型。 如：for (int i = 0; i < len; i++)。

2.9 泛型变量名

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

1. 单个的大写字母，后面可以跟一个数字（如：E, T, X, T2）。
2. 以类命名方式（参考类名），后面加个大写的 T（如：RequestT, FooBarT）。

2.10 id命名

插件 apply plugin: 'kotlin-android-extensions'，可以在代码中通过 xml 定义的控件 id 直接操作控件，而不用写 findViewById ，所以这里控件的命名直接使用 lowerCamelCase 风格编写。

命名规则：view 缩写{模块名}逻辑名，例如： btnMainSearch、btnBack。

三、Kotlin代码样式

3.1 类型推断

在可能的情况下，应选择使用类型推断代替显式声明实际的类型。

// BAD
val something: MyType = MyType()
val meaningOfLife: Int = 42
// GOOD
val something = MyType()
val meaningOfLife = 42

3.2 分号

应该尽可能避免在Kotlin中使用分号。

// BAD
val horseGiftedByTrojans = true;
if (horseGiftedByTrojans) {
    bringHorseIntoWalledCity();
}
// GOOD
val horseGiftedByTrojans = true
if (horseGiftedByTrojans) {
    bringHorseIntoWalledCity()
}

3.3 声明When

如果应该以相同的方式处理它们，请使用逗号分隔。始终包括else情况。

// BAD
when (anInput) {
    1 -> doSomethingForCaseOne()
    2 -> doSomethingForCaseOneOrTwo()
    3 -> doSomethingForCaseThree()
}
// GOOD
when (anInput) {
    1, 2 -> doSomethingForCaseOneOrTwo()
    3 -> doSomethingForCaseThree()
    else -> println("No case satisfied")
}

3.4 可空类型

避免使用 !! ，减少出现空指针的情况。

// BAD
editText!!.setText("foo")
tvTitle.setText(title!!)
// GOOD
editText?.setText("foo")
tvTitle.setText(title ?: "") or title?.let { tvTitle.setText(it) }

3.5 语言

使用美式英语 拼写。

// BAD
val colourName = "red"
// GOOD
val colorName = "red"

3.6 大括号

左大括号不单独占一行，与其前面的代码位于同一行：

class MyClass {
    fun func(): Int {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

我们需要在条件语句周围添加大括号。例外情况：如果整个条件语句（条件和主体）适合放在同一行，那么您可以（但不是必须）将其全部放在一行上。例如，我们接受以下样式：

if (condition) {
    body()
}

同样也接受以下样式：

if (condition) body()

但不接受以下样式：

if (condition)
    body()  // bad!

3.7 编写简短方法

在可行的情况下，尽量编写短小精炼的方法。有些情况下较长的方法是恰当的，因此对方法的代码长度没有做出硬性限制。如果某个方法的代码超出 40 行，请考虑是否可以在不破坏程序结构的前提下对其拆解，一个方法最好只做一件事情。

3.8 类成员的顺序

这并没有唯一的正确解决方案，但如果都使用一致的顺序将会提高代码的可读性，推荐使用如下排序：

1. 常量
2. 字段（public -> protected -> private）
3. 构造函数
4. 重写函数和回调 （在Android 中，应该将生命周期的函数放在前面）
5. 公有函数
6. 私有函数
7. 内部类或接口

class MainActivity : Activity() {

    companion object {
        private const val TAG = "tag"
    }

    var updateTime = 0L
    protected var mContent = ""
    private  var mTitle = ""
    private lateinit var mTextViewTitle: TextView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
    }

    fun setTitle(title:String){
        mTitle = title
    }

    private fun setUpView(){
        ...
    }

    inner class AnInnerClass{
       
    }
}

如果类继承于 Android 组件（例如 Activity 或 Fragment），那么把重写函数按照他们的生命周期进行排序是一个非常好的习惯，例如，Activity 实现了 onCreate()、onDestroy()、onPause()、onResume()，它的正确排序如下所示：

class MainActivity : Activity() {
    // Order matches Activity lifecycle
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

    }

    override fun onResume() {
        super.onResume()

    }

    override fun onPause() {
        super.onPause()

    }

    override fun onDestroy() {
        super.onDestroy()
       
    }
}

3.9 函数参数的排序

在 Android 开发过程中，Context 在函数参数中是再常见不过的了，我们最好把 Context 作为其第一个参数。

把回调接口或函数应该作为其最后一个参数。

// Context always goes first
fun loadUser(context: Context, userId: Int): User

// Callbacks or funcation always go last
fun loadUserAsync(context: Context, userId: Int, callback: UserCallback)
fun loadUserAsync(context: Context, userId: Int, action: (User) -> Unit)

3.10 字符串常量的命名和值

Android SDK 中的很多类都用到了键值对函数，比如 SharedPreferences、Bundle、Intent，所以，即便是一个小应用，我们最终也不得不编写大量的字符串常量。

当时用到这些类的时候，我们 必须 将它们的键定义为 static final 字段，并遵循以下指示作为前缀。

类	字段名前缀
SharedPreferences	PREF_
Bundle	BUNDLE_
Fragment Arguments	ARGUMENT_
Intent Extra	EXTRA_
Intent Action	ACTION_
onSaveInstanceState	SAVED_

说明：虽然 Fragment.getArguments() 和 onSaveInstanceState 也是 Bundle ，但因为这是 Bundle 的常用用法，所以特意为此定义一个不同的前缀。

3.11 行长限制

代码中每一行文本的长度都应该不超过 100 个字符。虽然关于此规则存在很多争论，但最终决定仍是以 100 个字符为上限，如果行长超过了 100（AS 窗口右侧的竖线就是设置的行宽末尾 ），我们通常有两种方法来缩减行长。

• 提取一个局部变量或方法（最好）。
• 使用换行符将一行换成多行。

不过存在以下例外情况：

• 如果备注行包含长度超过 100 个字符的示例命令或文字网址，那么为了便于剪切和粘贴，该行可以超过 100 个字符。
• 导入语句行可以超出此限制，因为用户很少会看到它们（这也简化了工具编写流程）。

3.11.1 换行策略

这没有一个准确的解决方案来决定如何换行，通常不同的解决方案都是有效的，但是有一些规则可以应用于常见的情况。

3.11.2 操作符的换行

除赋值操作符之外，我们把换行符放在操作符之前，例如：

int longName = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne
        + theFinalOne;

赋值操作符的换行我们放在其后，例如：

int longName =
        anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne + theFinalOne;

3.11.3 函数链的换行

当同一行中调用多个函数时（比如使用构建器时），对每个函数的调用应该在新的一行中，我们把换行符插入在 . 之前。

例如：

Picasso.with(context).load("https://blankj.com/images/avatar.jpg").into(ivAvatar);

我们应该使用如下规则：

Picasso.with(context)
        .load("https://blankj.com/images/avatar.jpg")
        .into(ivAvatar);

3.11.4 多参数的换行

当一个方法有很多参数或者参数很长的时候，我们应该在每个 , 后面进行换行。

比如：

loadPicture(context, "https://blankj.com/images/avatar.jpg", ivAvatar, "Avatar of the user", clickListener);

我们应该使用如下规则：

loadPicture(context,
        "https://blankj.com/images/avatar.jpg",
        ivAvatar,
        "Avatar of the user",
        clickListener);

3.11.5 RxJava 链式的换行

RxJava 的每个操作符都需要换新行，并且把换行符插入在 . 之前。

例如：

public Observable<Location> syncLocations() {
    return mDatabaseHelper.getAllLocations()
            .concatMap(new Func1<Location, Observable<? extends Location>>() {
                @Override
                 public Observable<? extends Location> call(Location location) {
                     return mRetrofitService.getLocation(location.id);
                 }
            })
            .retry(new Func2<Integer, Throwable, Boolean>() {
                 @Override
                 public Boolean call(Integer numRetries, Throwable throwable) {
                     return throwable instanceof RetrofitError;
                 }
            });
}

四、Android资源文件

资源文件命名为全部小写，采用下划线命名法，资源文件需带module名作为前缀。

4.1 动画资源文件（anim/ 和 animator/）

安卓主要包含属性动画和视图动画，其视图动画包括补间动画和逐帧动画。属性动画文件需要放在 res/animator/ 目录下，视图动画文件需放在 res/anim/ 目录下。

命名规则：module_逻辑名称。

例如：common_refresh_progress.xml

如果是普通的补间动画或者属性动画，可采用：动画类型_方向 的命名方式。

例如：

名称	说明
module_fade_in	淡入
module_fade_out	淡出
module_push_down_in	从下方推入
module_push_down_out	从下方推出
module_push_left	推向左方
module_slide_in_from_top	从头部滑动进入
module_zoom_enter	变形进入
module_slide_in	滑动进入
module_shrink_to_middle	中间缩小

4.2 颜色资源文件（color/）

命名规则：module_类型_逻辑名称。

例如：module_sel_btn_font.xml。

颜色资源也可以放于 res/drawable/ 目录，引用时则用 @drawable 来引用，但不推荐这么做，最好还是把两者分开。

4.3 图片资源文件（drawable/ 和 mipmap/）

res/drawable/ 目录下放的是位图文件（.png、.9.png、.jpg、.gif）或编译为可绘制对象资源子类型的 XML 文件，而 res/mipmap/ 目录下放的是不同密度的启动图标，所以 res/mipmap/ 只用于存放启动图标，其余图片资源文件都应该放到 res/drawable/ 目录下。

命名规则：module_类型_逻辑名称

例如：user_btn_logout.png

大分辨率图片（单维度超过 1000）建议统一放在 xxhdpi 目录下管理，否则将导致占用内存成倍数增加 。

如果有多种形态，如按钮选择器：module_sel_btn_xx.xml，采用如下命名：

名称	说明
module_sel_btn_xx	作用在 btn_xx 上的 selector
module_btn_xx_normal	默认状态效果
module_btn_xx_pressed	state_pressed 点击效果
module_btn_xx_focused	state_focused 聚焦效果
module_btn_xx_disabled	state_enabled 不可用效果
module_btn_xx_checked	state_checked 选中效果
module_btn_xx_selected	state_selected 选中效果
module_btn_xx_hovered	state_hovered 悬停效果
module_btn_xx_checkable	state_checkable 可选效果
module_btn_xx_activated	state_activated 激活效果
module_btn_xx_window_focused	state_window_focused 窗口聚焦效果

注意：使用 Android Studio 的插件 SelectorChapek 可以快速生成 selector，前提是命名要规范。

4.4 布局资源文件（layout/）

按照对应类型增加前缀：

类型	前缀
Activity	module_activity
Fragment	module_fragment
Dialog	module_dialog
include	module_include
ListView	module_list_item
RecyclerView	module_recycle_item
GridView	module_grid_item

Activity/Fragment/Dialog的类名不需要增加module前缀，直接为每一个module分配一个package，比如：a.b.c.user、a.b.c.launch，所有的代码都放在该package下。

4.5 菜单资源文件（menu/）

命名规则：module_逻辑名称

4.6 values 资源文件（values/）

values/ 资源文件下的文件都以 s 结尾，如 attrs.xml、colors.xml、dimens.xml，起作用的不是文件名称，而是 标签下的各种标签，比如