Android 代码规范

Posted 2022-05-31 王永迪

前言

这份文档参考了 Google Java 编程风格规范和 Google 官方 Android 编码风格规范。该文档仅供参考，只要形成一个统一的风格，见量知其意就可。

源文件基础

编码格式

源文件编码格式为 UTF-8。

文件名

源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。

源文件结构

许可证与版权信息

如果一个文件包含许可证或版权信息，那么它应当被放在文件最前面。

package语句

package 语句不换行，列限制(3.4节)并不适用于package语句。(即package语句写在一行里)

import语句

1、import不要使用通配符：

即，不要出现类似这样的import语句：import java.util.*;

2、不要换行：

import语句不换行，列限制(4.4节)并不适用于import语句。(每个import语句独立成行)

类成员区顺序

类成员顺序对代码的可读性是有很大帮助的，从上到下的排列顺序为：

常量区
UI控件变量区
普通变量区
重载方法区（重载，永不分离）
声明周期区（在生命周期区方法内加入需要执行的代码）

类成员划分

按照发生的先后顺序排列
常量按照使用先后排列
UI控件成员变量按照layout文件中的先后顺序排列
普通成员变量按照使用的先后顺序排列
方法基本上都按照调用的先后顺序在各自区块中排列

格式术语

大括号

1、使用大括号(即使是可选的)

大括号与if, else, for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。

2、非空块：K & R 风格

对于非空块和块状结构，大括号遵循 Kernighan 和 Ritchie 风格 (Egyptian brackets):
左大括号前不换行；
左大括号后换行；
右大括号前换行；
如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。

例如，如果右大括号后面是else或逗号，则不换行。
示例：

return new MyClass()     
    @Override 
    public void method()         
        if (condition()) 
            try 
                something();
             catch (ProblemException e) 
                recover();
            
        
    
;

空块：可以用简洁版本

一个空的块状结构里什么也不包含，大括号可以简洁地写成，不需要换行。
例外：如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ，即使大括号内没内容，右大括号也要换行。
示例：

void doNothing() 

块缩进

每当开始一个新的块，缩进增加4个空格，当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见3.1.2节中的代码示例)

一行一个语句

每个语句后要换行。

列限制

一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。

空白

垂直空白

有且只有一个换行

类成员区划分
在方法体内，语句的逻辑分组间使用空行。
类的第一个成员与最后一个成员的空白。

水平空白

类型和变量之间：List list
分隔任何保留字与紧随其后的左括号(()(如if, for catch等)。
如果在一条语句后做注释，则双斜杠(//)两边都要空格。
在, : ;及右括号())后

具体结构

1、枚举类

枚举常量间用逗号隔开，换行可选。

private enum Suit  
    CLUBS, 
    HEARTS, 
    SPADES, 
    DIAMONDS

2、变量声明

1）、每次只声明一个变量

不要使用组合声明，比如int a, b;

2）、需要时才声明，并尽快进行初始化

不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。

3、数组

1）、非C风格的数组声明

中括号是类型的一部分：String[] args， 而非 String args[]

4、switch语句

每个switch语句都包含一个default语句组，即使它什么代码也不包含。

5、注解(Annotations)

1）、方法注解

注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。

2）、变量注解

没有特殊限制，也可以写成：
@Partial @Mock DataLoader loader;

6、Modifiers（修饰）

类和成员的modifiers如果存在，则按Java语言规范中推荐的顺序出现。
public protected private abstract static final transient volatile synchronized native strictfp

命名规范

包名

包名全部小写，连续的单词只是简单地连接起来，不使用下划线。
例如：com.shuidi.huzhu

类名

类名都以UpperCamelCase风格编写，后缀类型，不要加下划线。
类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。名词，采用大驼峰命名法，尽量避免缩写，除非该缩写是众所周知的， 比如html,URL，如果类名称中包含单词缩写，则单词缩写的每个字母均应大写。

WelcomeActivity、NewDetailAdapter、HomePosterParser、ThreadPoolManager等等

测试类的命名以它要测试的类的名称开始，以Test结束。
例如：HashTest 或 HashIntegrationTest。
接口（interface）：命名规则与类一样采用大驼峰命名法，多以able或ible结尾，如
interface Runnable ;
interface Accessible;

方法名

方法名都以 LowerCamelCase 风格编写。
方法名通常是动词或动词短语。

初始化方法，命名以init开头，例：initView
按钮点击方法，命名以to开头，例：toLogin
设置方法，命名以set开头，例：setData
具有返回值的获取方法，命名以get开头，例：getData
通过异步加载数据的方法，命名以load开头，例：loadData
布尔型的判断方法，命名以is或has，或具有逻辑意义的单词如equals，例：isEmpty

常量名

全部为大写单词，单词之间用下划线分开。
public final static int PAGE_SIZE = 20;

参数名、变量名

1、控件类型

类型描述+范围描述+意义描述的组合，用驼峰式，首字母小
private TextView tvHeaderTitle; // 标题栏的标题
private Button btnLogin; // 登录按钮

2、其他类型

范围描述+意义描述+类型描述的组合，用驼峰式，首字母小
private ArrayList<String> commentList; 
private String content; 

资源文件命名

资源文件命名与java命名不同，大多采用前缀命名法，对类型进行区分

1、控件ID命名

<!-- 这是标题栏的标题 -->
<TextView
    android:id="@+id/txt_header_title"
    ... />

<!-- 这是登录按钮 -->
<Button
    android:id="@+id/btn_login"
    ... />

2、layout命名

组件类型范围功能，范围可选，只在有明确定义的范围内才需要加上。

activity_范围_功能，为Activity的命名格式 
fragment_范围_功能，为Fragment的命名格式
dialog_范围_功能，为Dialog的命名格式 
item_范围_功能，为列表的item命名格式
widget_范围_功能，为自定义控件类命名格式
header_范围_功能，为列表的HeaderView命名格式
footer_范围_功能，为列表的FooterView命名格式

3、string的命名

类型范围功能，范围可选。
传统命名方式：

页面标题，命名格式为：title_页面
按钮文字，命名格式为：btn_按钮事件
标签文字，命名格式为：label_标签文字
选项卡文字，命名格式为：tab_选项卡文字
消息框文字，命名格式为：toast_消息
编辑框的提示文字，命名格式为：hint_提示信息
图片的描述文字，命名格式为：desc_图片文字
对话框的文字，命名格式为：dialog_文字
menu的item文字，命名格式为：action_文字

建议命名方式：
String命名如果以传统命名法来命名，有些按照业务逻辑进行命名，好处是可插拔，坏处是资源命名满天飞，迭代周期久后导致过于臃肿，建议根据实际意义进行命名。

示例：

我的优惠券 ：str_mine_coupon
支付 ：str_pay

4、colors的命名
传统命名方式：
前缀控件范围_后缀，控件、范围、后缀可选，但控件和范围至少要有一个。

背景颜色，添加bg前缀
文本颜色，添加text前缀
分割线颜色，添加div前缀
区分状态时，默认状态的颜色，添加normal后缀
区分状态时，按下时的颜色，添加pressed后缀
区分状态时，选中时的颜色，添加selected后缀
区分状态时，不可用时的颜色，添加disable后缀

建议命名方式：

由于色值复用较多，个人建议采用更为直接的匈牙利命名法，达到更直观，更简洁的使用

示例：

正常颜色 ：col_000000
带透明度颜色 ：col_000000_translucent25 

5、drawable的命名

前缀控件范围_后缀，控件、范围、后缀可选，但控件和范围至少要有一个。

图标类，添加ic前缀
背景类，添加bg前缀
分隔类，添加div前缀
默认类，添加def前缀
区分状态时，默认状态，添加normal后缀
区分状态时，按下时的状态，添加pressed后缀
区分状态时，选中时的状态，添加selected后缀
区分状态时，不可用时的状态，添加disable后缀
多种状态的，添加selector后缀（一般为ListView的selector或按钮的selector）

6、动画文件命名

动画类型_动画方向。

fade_in，淡入
fade_out，淡出
push_down_in，从下方推入
push_down_out，从下方推出
slide_in_from_top，从头部滑动进入
zoom_enter，变形进入
shrink_to_middle，中间缩小

附录：

1、 UI控件缩写表 : 建议控件的命名以前缀命名

LinearLayout    ll  llFriend
RelativeLayout  rl  rlMessage
FrameLayout     fl  flCart
TableLayout     tl  tlTab
Button      btn     btnHome
ImageButton     ibtn    btnPlay
TextView    tv  tvName
EditText    et  etName
ListView    lv  lvCart
RecycleView     rv  rvTopic
ImageView   iv  ivHead
GridView    gv  gvPhoto

2、常见英文单词缩写表

icon        ic 
color       col
divider     di
selector    sl
average     avg
background  bg
buffer      buf
control     ctrl
delete      del
document    doc
error       err
escape      esc
increment   inc
infomation  info
initial     init
image       img
length      len
library     lib
message     msg
password    pwd
position    pos
server      srv
source      src
string      str
temp        tmp
window      win