程序员必知的Android 代码规范

前言

虽然我们项目的代码时间并不长，也没经过太多人手，但代码的规范性依然堪忧，目前存在较多的比较自由的「代码规范」，这非常不利于项目的维护，代码可读性也不够高，

此外，客户端和后端的研发模式也完全不同，后端研发基本都是基于 SOA 思想的，通常一个子系统 3 个人一起维护就已经是很充分的人力了，更多时候就是 1 个主力 + 1 个 backup 的人力配置。

而客户端却完全不同，大家的代码都是相互交叉的，一个模块的代码可能要经历数十人的蹂躏，所以形成一个一致的开发规范迫在眉睫。

为什么需要一致的代码规范？

核心还是减少沟通成本，提升我们的 Code Review 效率，让我们的代码更加易于维护。此外，一个一致的代码规范可以造成更少的 bug，也就意味着更节省时间和金钱。

当然，规范是约定的，本系列文字全是笔者多年来博采众长，积累而成，所以有任何不同意见，欢迎评论拍砖。

1. Android 的工具规范

工欲善其事，必先利其器。

由于 Android 基本都基于 Android Studio 进行开发，所以工具规范全部以 Android Studio 为前提。

1. 必须使用最新的稳定版本的 Android Studio 进行开发；
2. 编码格式必须统一为 UTF-8；

3. 删除多余的 import，减少警告出现，可利用 AS 的 Optimize Imports（Settings -> Keymap -> Optimize Imports）快捷键，设置自己的喜好。

   

4. 编辑完 .java、.kt、.xml 等文件后必须格式化（需要在设置好以下几点的前提下）

Reformat Code 的必要性，一定需要保证 IDE 配置一致为前提，尽可能贴切于 Android Studio 默认。
强烈建议对于比较长的老代码局部格式化，不全局格式化

• 每行字符数不得超过 160 字符，设置 Editor -> Code Style

  

• 全部设置为单路径引用，kotlinx.android.synthetic.main 除外。

  

以上几处设置完毕，其他采用 Android Studio 默认方式，再进行 Reformat Code 快捷键即可。

2. Android 的分包规范

前面强调了工具的统一配置，再利用 Android Studio 本身的功能便可把代码风格变得一致。接下来就带来第二部分：Android 的分包规范。

对于分包，我们需要达成一致，我们采用 PBF 方式，不推荐使用 PBL 方式。

PBF（按功能分包 Package By Feature）
PBL（按层分包 Package By Layer）

PBF 可能不是很好区分在哪个功能中，不过也比 PBL 要好找很多，且 PBF 与 PBL 相比较有如下优势：

• package 内高内聚，package 间低耦合
  哪块要添新功能，只改某一个 package 下的东西，而PBL 需要改多个 package，非常麻烦。
• package 有私有作用域（package-private scope）
  原则上一个 package 下的不允许其他类访问都是不应该加上 public 的。
• 很容易删除功能
  统计发现新功能没人用，这个版本那块功能得去掉。如果是 PBL，得从功能入口到整个业务流程把受到牵连的所有能删的代码和 class 都揪出来删掉，一不小心就完蛋。如果是 PBF，好说，先删掉对应包，再删掉功能入口（删掉包后入口肯定报错了），完事。
• 高度抽象
  解决问题的一般方法是从抽象到具体，PBF 包名是对功能模块的抽象，包内的 class 是实现细节，符合从抽象到具体，而 PBL 弄反了。PBF 从确定 AppName 开始，根据功能模块划分 package，再考虑每块的具体实现细节，而 PBL 从一开始就要考虑要不要 dao 层，要不要 com 层等等。
• 只通过 class 来分离逻辑代码
  PBL 既分离 class 又分离 package，而 PBF 只通过 class 来分离逻辑代码。
• package 的大小有意义了
  PBL 中包的大小无限增长是合理的，因为功能越添越多，而 PBF 中包太大（包里 class 太多）表示这块需要重构（划分子包）。

3. Android 的命名规范

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

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

3.1 包名

Android 里面有 package 的概念，所以需要约定一下包名命名规范。

包名全部小写，不允许出现中文、大写字母或者下划线，前面为子模块命名，再根据 PBF 方式进行命名。

3.2 类名

类名都以 UpperCamelCase 风格编写。

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

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

类	描述	例如
Activity 类	模块名 + Activity	闪屏页类 SplashActivity
Fragment 类	模块名 + Fragment	主页类 HomeFragment
Service 类	模块名 + Service	时间服务 TimeService
BroadcastReceiver 类	功能名 + Receiver	推送接收 JPushReceiver
ContentProvider 类	功能名 + Provider	ShareProvider
自定义 View	功能名 + View/ViewGroup(组件名称)	ShapeButton
Dialog对话框	功能名+Dialog	ImagePickerDialog
Adapter 类	模块名 + Adapter	课程详情适配器 LessonDetailAdapter
解析类	功能名 + Parser	首页解析类 HomePosterParser
工具方法类	功能名 + Utils 或 Manager	线程池管理类：ThreadPoolManager

日志工具类：LogUtils（Logger 也可）
打印工具类：PrinterUtils |
| 数据库类 | 功能名 + DBHelper | 新闻数据库：NewsDBHelper |
| 自定义的共享基础类 | Base + 基础 | BaseActivity, BaseFragment |
| 抽象类 | Base / Abstract 开头 | AbstractLogin |
| 异常类 | Exception 结尾 | LoginException |
| 接口 | able / ible 结尾 / I 开头 | Runnable, Accessible ，ILoginView |

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

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

注意：如果项目采用 MVP，所有 Model、View、Presenter 的接口都以 I 为前缀，不加后缀，其他的接口采用上述命名规则。

3.3 方法名

方法名都以 lowerCamelCase 风格编写。

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

方法	说明
initXX()	初始化相关方法，使用 init 为前缀标识，如初始化布局 initView()
isXX(), checkXX()	方法返回值为 boolean 型的请使用 is/check 为前缀标识
getXX()	返回某个值的方法，使用 get 为前缀标识
setXX()	设置某个属性值
handleXX(), processXX()	对数据进行处理的方法
displayXX(), showXX()	弹出提示框和提示信息，使用 display/show 为前缀标识
updateXX()	更新数据
saveXX(), insertXX()	保存或插入数据
resetXX()	重置数据
clearXX()	清除数据
removeXX(), deleteXX()	移除数据或者视图等，如 removeView()
drawXX()	绘制数据或效果相关的，使用 draw 前缀标识

3.4 变量命名

这里的变量为广义的变量，包括了常量、局部变量、全局变量等，它们的基础规则是：

• 类型需要是名词 / 名词短语；
• 采用 lowerCamelCase 风格；

在具体的变量命名时，会根据该变量的类型不同而附加额外的命名规则：

类型	说明	例如
常量	大写 & 下划线隔开，Kotlin 一定要 const val	const val TYPE_NORMAL = 1
static final TYPE_NORMAL = 1
临时变量名	整型：i、j、k、m、n ，字符型一般用 c、d、e	for(int i = 0;i < len; i++)
其他变量	lowerCamelCase 风格即可，私有变量也不要使用 m 开头	private int tmp;
Kotlin	只读变量使用 val，可变变量使用 var，尽可能使用 val	var tmp = 0
val defaultIndex = 0

3.5 资源命名

Android 的资源包括：

资源文件命名为全部小写，采用下划线命名法。

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

安卓主要包含属性动画和视图动画，其视图动画包括补间动画和逐帧动画。属性动画文件需要放在 res/animator/ 目录下，视图动画文件需放在 res/anim/ 目录下。命名规则：{模块名_}逻辑名称。

说明： {} 中的内容为可选， 逻辑名称 可由多个单词加下划线组成。例如： refresh_progress.xml、 market_cart_add.xml、 market_cart_remove.xml。

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

例如：

名称	说明
fade_in	淡入
fade_out	淡出
push_down_in	从下方推入
push_down_out	从下方推出
push_left	推向左方
slide_in_from_top	从头部滑动进入
zoom_enter	变形进入
slide_in	滑动进入
shrink_to_middle	中间缩小

3.5.2 颜色资源文件（color/）

color/ 是专门用于存放颜色相关资源的文件夹。命名规则：类型{_模块名}_逻辑名称。

说明： {} 中的内容为可选。例如： sel_btn_font.xml。

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

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

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

命名规则：类型{_模块名}_逻辑名称、类型{_模块名}_颜色。

说明： {} 中的内容为可选； 类型 可以是可绘制对象资源类型，也可以是控件类型最后可加后缀 _small 表示小图， _big 表示大图。

例如：

名称	说明
btn_main_about.png	主页关于按键 类型_模块名_逻辑名称
btn_back.png	返回按键 类型_逻辑名称
divider_maket_white.png	商城白色分割线 类型_模块名_颜色
ic_edit.png	编辑图标 类型_逻辑名称
bg_main.png	主页背景 类型_逻辑名称
btn_red.png	红色按键 类型_颜色
btn_red_big.png	红色大按键 类型_颜色
ic_avatar_small.png	小头像图标 类型_逻辑名称
bg_input.png	输入框背景 类型_逻辑名称
divider_white.png	白色分割线 类型_颜色
bg_main_head.png	主页头部背景 类型_模块名_逻辑名称
def_search_cell.png	搜索页面默认单元图片 类型_模块名_逻辑名称
ic_more_help.png	更多帮助图标 类型_逻辑名称
divider_list_line.png	列表分割线 类型_逻辑名称
sel_search_ok.xml	搜索界面确认选择器 类型_模块名_逻辑名称
shape_music_ring.xml	音乐界面环形形状 类型_模块名_逻辑名称

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

名称	说明
sel_btn_xx	作用在 btn_xx 上的 selector
btn_xx_normal	默认状态效果
btn_xx_pressed	state_pressed 点击效果
btn_xx_focused	state_focused 聚焦效果
btn_xx_disabled	state_enabled 不可用效果
btn_xx_checked	state_checked 选中效果
btn_xx_selected	state_selected 选中效果
btn_xx_hovered	state_hovered 悬停效果
btn_xx_checkable	state_checkable 可选效果
btn_xx_activated	state_activated 激活效果
btn_xx_window_focused	state_window_focused 窗口聚焦效果

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

3.5.4 布局资源文件（layout/）

命名规则：类型_模块名、{模块名_}类型_逻辑名称。(也采用 PBF，方便查看，尤其在大项目中)

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

例如：

类型	名称	说明
Activity	main_activity.xml	主窗体 模块名_类型
Fragment	music_fragment.xml	音乐片段 模块名_类型
Dialog	loading_dialog.xml	加载对话框 逻辑名称_类型
PopupWindow	info_ppw.xml	信息弹窗（PopupWindow） 逻辑名称_类型
adapter 的列表项	main_song_item.xml	主页歌曲列表项 模块名_类型_逻辑名称

3.5.5 布局资源 id 命名

命名规则：{模块名_}_逻辑名_view 缩写（功能），例如： main_search_btn、back_btn。此外，采用 Kotlinx 直接获取布局文件的时候，id 命名采用驼峰样式。

说明： {} 中的内容为可选。参考 GoogleSamples Demo： https://github.com/android/architecture-samples

例如：

类型	规范	命名示例
TextView	xxx_text	user_login_text
EditText	xxx_edit	user_login_edit
ImageView	xxx_iv	user_login_iv
Button	xxx_btn	user_login_btn
CheckBox	xxx_cb	user_login_cb
GridView	xxx_gv	user_login_gv
ListView	xxx_lv	user_login_lv
RecyclerView	xxx_rv	user_login_rv
RadioButton	xxx_rb	user_login_rb
LinearLayout	xxx_ll	user_login_ll
RelativeLayout	xxx_rl	user_login_rl
FrameLayout	xxx_fl	user_login_fl
GridLayout	xxx_gl	user_login_gl
ConstraintLayout	xxx_cl	user_login_cl

3.5.6 菜单资源文件（menu/）

菜单相关的资源文件应放在该目录下。命名规则：{模块名_}逻辑名称

说明： {} 中的内容为可选。例如： main_drawer.xml、 navigation.xml。

3.5.7 colors.xml

的 name 命名使用下划线命名法，在你的 colors.xml 文件中应该只是映射颜色的名称一个 ARGB 值，而没有其它的。不要使用它为不同的按钮来定义 ARGB 值。

例如，不要像下面这样做：

  
      #FFFFFF
      #2A91BD
      #5F5F5F
      #939393
      #FFFFFF
      #FF9D2F
      ...
      #323232

使用这种格式，会非常容易重复定义 ARGB 值，而且如果应用要改变基色的话会非常困难。同时，这些定义是跟一些环境关联起来的，如 button 或者 comment，应该放到一个按钮风格中，而不是在 colors.xml 文件中。

相反，应该这样做：

  

      
      #FFFFFF
      #DBDBDB
      #939393
      #5F5F5F
      #323232

      
      #27D34D
      #2A91BD
      #FF9D2F
      #FF432F

  

向应用设计者那里要这个调色板，名称不需要跟 "green"、"blue" 等等相同。"brand_primary"、"brand_secondary"、"brand_negative" 这样的名字也是完全可以接受的。像这样规范的颜色很容易修改或重构，会使应用一共使用了多少种不同的颜色变得非常清晰。通常一个具有审美价值的 UI 来说，减少使用颜色的种类是非常重要的。

注意：如果某些颜色和主题有关，那就单独写一个 colors_theme.xml。

3.5.8 strings.xml

的 name 命名使用下划线命名法，采用以下规则：{模块名_}逻辑名称，这样方便同一个界面的所有 string 都放到一起，方便查找。

名称	说明
main_menu_about	主菜单按键文字
friend_title	好友模块标题栏
friend_dialog_del	好友删除提示
login_check_email	登录验证
dialog_title	弹出框标题
button_ok	确认键
loading	加载文字

3.5.9 styles.xml

应用到 TextView 中：

或许你需要为按钮控件做同样的事情，不要停止在那里，将一组相关的和重复 android:xxxx 的属性放到一个通用的