Android 编码规范

简单总结了 Android 开发中的一些代码规范，供开发者参考。

1 命名规范

大驼峰命名（UpperCamelCase）：每个单词的第一个字母都大写。

小驼峰命名（lowerCamelCase）：除第一个单词以外，每一个单词的第一个字母大写。

命名的基本原则：

• 不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
• 严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。但比如 shanghai 等通用的名称，可视同英文。
• 除了常见的英文缩写，尽量避免缩写。

1.1 类 / 接口命名

• 使用大驼峰命名法，用名词或者名词词组命名，每个单词的首字母大写。
• 尽量避免大写，除非该缩写是众所周知的，比如 URL、 HTML 等。
• 接口命名规则与类一样采用大驼峰命名法，多以 able 或 ible 结尾，如 interfaceRunnable、 interfaceAccessible 。
• 若项目采用 MVP 架构，接口都以 I 为前缀，不加后缀，其他的接口采用上述命名规则。比如 interfaceIUserTest。
• 常见类名命名规则如下：

1.2 变量命名

• 成员变量 / 局部变量
• 使用小驼峰命名。
• 不推荐使用谷歌的前面加 m 的编码风格。
• 控件变量
• 使用小驼峰命名。
• 建议使用 控件缩写+逻辑名称 格式，例如 btnLogin、 etUserName 。
• 对应的控件 id 命名为 控件缩写_逻辑名称，例如 btn_login、 et_user_name 。
• 常见控件缩写如下：

1.3 常量命名

• 单词每个字母均大写。
• 单词之间用下划线连接，力求语义表达完整清楚，不要嫌名字长。

1.4 方法命名

• 使用小驼峰命名。
• 方法名通常是动词或动词短语，保证见名知义，尽量不适用 or 或者 and，遵循 “ do one thing ” 原则。
• 一个方法尽量不要超过 50 行，如果方法太长，说明当前方法业务逻辑已经非常复杂，那么就需要进行方法拆分。

1.5 资源文件命名

全部小写，采用下划线命名法。

1.5.1 布局文件命名（xml 文件）

以对应的类别名称为前缀，逻辑名称在后，以下划线连接。

1.5.2 drawable 文件命名

以用途缩写作为前缀，逻辑名称在后，以下划线连接，区分状态时，添加状态后缀。

1.5.3 动画文件命名（anim 文件夹下）

规则：动画类型_动画方向。

1.5.4 values 中 name 命名

1.5.4.1 strings.xml

• 命名格式：xx 界面 + 逻辑功能 ，如 activity_home_welcome_str。
• 建议把同一个界面的所有 String 都在一起，方便查找。

1.5.4.2 styles.xml

• 使用大驼峰命名法，主题可以命名为 XXTheme ，控件的风格可以命名为 XXStyle 。

1.5.4.3 colors.xml

• 命名格式：color_16进制颜色值
• 不要为某个控件指定特定颜色，比如 bg_login ，这样非常容易重复定义颜色值。

<resources>

    <color name="red_FF432F">#FF432F</color>
    <color name="red_FF0000">#FF0000</color>

</resources>

1.5.4.4 dimens.xml

• 可以和 colors.xml 中命名格式类似
• 必要时也可用”逻辑名称_功能“ 命名

<resources>

    <!-- font sizes -->
    <dimen name="font_22">22sp</dimen>
    <dimen name="font_12">12sp</dimen>

    <!-- typical spacing between two views -->
    <dimen name="spacing_40">40dp</dimen>
    <dimen name="spacing_4">4dp</dimen>

    <!-- typical sizes of views -->
    <dimen name="button_height_60">60dp</dimen>
    <dimen name="button_height_40">40dp</dimen>

</resources>

2 注释规范

类、类属性、类方法的注释必须使用 Javadoc 规范，使用 /** XXX */格式，不得使用 // XXX 方式。

2.1 类和接口注释

类和接口统一添加 Javadoc 注释，要求至少写出创建者、创建时间以及内容简要说明。具体可以在 AS 中自己配制， Settings→Editor→FileandCodeTemplates→Includes→FileHeader，格式如下：

/**
 * author : xxx
 * e-mail : xxx@xx
 * time   : 2017/08/28
 * desc   :
 */

2.2 方法注释

下面几种方法，都必须添加 Javadoc 注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

• 接口中定义的所有方法
• 抽象类中自定义的抽象方法
• 抽象父类的自定义公用方法
• 工具类的公用方法

/** 方法的一句话概述
* 方法详述（简单方法可不必详述）
* @param s 说明参数含义
* @return 说明返回值含义
* @throws IOException 说明发生此异常的条件
* @throws NullPointerException 说明发生此异常的条件
*/

2.3 变量和常量注释

下面几种情况下的常量和变量，都要添加注释说明，优先采用右侧 // 来注释，若注释说明太长则在上方添加注释。

• 接口中定义的所有常量
• 公有类的公有常量
• 枚举类定义的所有枚举常量
• 实体类的所有属性变量

2.4 方法体内代码的注释

• 方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。
• 方法内部多行注释使用 /* ... */ 注释。
• 注意与代码对齐， * 及 // 与其后文字之间空一格。
• 不要在方法内部使用 Javadoc 形式的注释。

2.5 其他一些注释

• 资源文件代码注释

<!-- 注释内容 -->

• AS 已帮你集成了一些注释模板，我们只需要直接使用即可，在代码中输入 todo、 fixme等这些注释模板，回车后便会出现如下注释：

// TODO: 2017/8/28 需要实现，但目前还未实现的功能的说明
// FIXME: 2017/8/28 需要修正，甚至代码是错误的，不能工作，需要修复的说明

3 格式规范

3.1 使用标准的大括号风格

• 大括号与 if,else,for,do,while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。
• 对于非空块和块状结构，大括号遵循 Kernighan 和 Ritchie 风格（R & N）
• 左大括号前不换行
• 右大括号前换行
• 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行；否则不换行。例如，如果右大括号后面是 else 或 catch，则不换行。

class MyClass {
    public void method() {
      if (condition()) {
        try {
          something();
        } catch (ProblemException e) {
          recover();
        }
      }
    }
}

• 一个空的块状结构里什么也不包含，大括号可以简洁地写成 {}，不需要换行。

3.2 限制代码行的长度

• 每行代码的长度不应该不超过 100 个字符。
• 例外： package和 import语句，不换行。
• 例外：注释中包含了超过 100 个字符的命令示例或者 URL，为了便于剪切和复制，其长度可以超过 100 个字符。

3.3 合理空白

• 垂直空白
• 方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。
• 水平空白
• 左小括号和右小括号与字符之间不出现空格。
• if/for/while/switch/do 等保留字与括号之间都必须加空格。
• 任何二目、三目运算符的左右两边都需要加一个空格。
• 方法参数在定义和传入时，多个参数逗号后边必须加空格。
• 请使用快捷键 ctrl+alt+L 格式化代码。