安卓开发规范

注：本文大部分节选自：http://www.jianshu.com/p/419f5357357d 如涉及版权问题,请联系我,将尽快删除。作者：Blankj

前言

为了利于项目维护以及规范开发，促进成员之间Code Review的效率，故提出以下开发规范，如有更好建议，请提出。

AndroidStudio规范

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

尽量使用最新版的IDE进行开发；
编码格式统一为UTF-8；
编辑完.java、 .xml等文件后一定要格式化（基本格式方面使用 AS 默认模板即可）；
删除多余的import，减少警告出现，可利用AS的Optimize Imports(Settings → Keymap → Optimize Imports)快捷键；
AS常用开发插件可以参考这里:AS常用开发插件
命名规范

代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。

注意：即使纯拼音命名方式也要避免采用。

包名

采用反域名命名规则，全部使用小写字母。一级包名是顶级域名，通常为com,edu,gov,net,org等，二级包名为公司名，三级包名根据应用进行命名，四级包名为模块名或层级名。

src
└─com
    └─domain
        └─app
            │  AppApplication.java  定义Application类
            │  Config.java          定义配置数据（常量）
            │
            ├─framework
            │      定义interface以及相关基类
            │
            ├─io
            │      数据定义(model)、数据操作(比如json解析，但不包括db操作)
            │
            ├─model
            │      定义model(数据结构以及getter/setter、compareTo、equals等等，不含复杂操作)
            │      以及modelHelper（提供便于操作model的api）
            │
            ├─provider
            │      实现ContentProvider，及其依赖的db操作
            │
            ├─receiver
            │      实现Receiver
            │
            ├─service
            │      实现Service（比如IntentService），用于在独立线程中异步do stuff
            │
            ├─ui
            │      实现BaseActivity，以及自定义view和widget，相关的Adapter也放这里
            │
            ├─util
            │      实现工具类，提供静态方法
            │
            ├─feature1
            │      Item.java                定义model
            │      ItemHelper.java          实现modelHelper
            │      feature1Activity.java    定义UI
            │      feature1DAO.java         私有db操作
            │      feature1Utils.java       私有工具函数
            │      ...其它私有class
            │
            ├─...其它feature

注意：如果项目采用MVP，所有M、V、P抽取出来的接口都放置在相应模块的i包下，所有的实现都放置在相应模块的impl下

类名

类名都以UpperCamelCase风格编写。类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。名词，采用大驼峰命名法，尽量避免缩写，除非该缩写是众所周知的，比如HTML, URL，如果类名称中包含单词缩写，则单词缩写的每个字母均应大写。

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

方法名

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

常量名

常量名命名模式为CONSTANT_CASE，全部字母大写，用下划线分隔单词。

变量

非常量字段名以lowerCamelCase风格的基础上改造为如下风格：基本结构为scopeVariableNameType。实体类中不得随意修改的成员变量可添加下划线前缀以作区别，例如：class User{ public int _id; }

注意：如果项目中使用ButterKnife，则不添加m前缀，以lowerCamelCase风格命名。

非静态字段命名以 m 开头，表示 member，如：mRun；
静态字段命名以 s 开头，表示 static，如：sInstance；
公有非静态字段命名以 p 开头；
公有静态字段（全局变量）命名以 g 开头；
控件变量添加组件前缀，顺序在所有者前缀之后，例如：全局名称 mBtnNext，局部名称 btnNext。

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

参数名

参数名以lowerCamelCase风格编写。参数应该避免用单个字符命名。

局部变量名

局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。

资源文件规范

资源布局文件（XML文件（layout布局文件））

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

contentView命名

必须以全部单词小写，单词间以下划线分割. 所有Activity或Fragment的contentView必须与其类名对应，对应规则为：将所有字母都转为小写，将类型和功能调换（也就是后缀变前缀）。例如：activity_main.xml

Dialog命名

规则：dialog_描述.xml 例如：dialog_hint.xml

PopupWindow命名

规则：ppw_描述.xml 例如：ppw_info.xml

列表项命名

规则：item_描述.xml 例如：item_city.xml

包含项命名

规则：模块_(位置)描述.xml 例如：activity_main_head.xml、activity_main_bottom.xml 注意：通用的包含项命名采用：项目名称缩写_描述.xml 例如：xxxx_title.xml

资源文件（图片drawable文件夹下）

全部小写，采用下划线命名法，加前缀区分命名模式：可加后缀 _small 表示小图， _big 表示大图，逻辑名称可由多个单词加下划线组成，采用以下规则：

用途_模块名_逻辑名称
用途_模块名_颜色
用途_逻辑名称
用途_颜色

说明：用途也指控件类型

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

动画文件（anim文件夹下）

全部小写，采用下划线命名法，加前缀区分。具体动画采用以下规则：模块名_逻辑名称。

values中name命名

colors.xml

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

<color name="button_foreground">#FFFFFF</color>

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

<resources>
     <!-- grayscale -->
      <color name="white"     >#FFFFFF</color>
      <color name="gray_light">#DBDBDB</color>
      <color name="gray"      >#939393</color>
      <color name="gray_dark" >#5F5F5F</color>
      <color name="black"     >#323232</color>
      <!-- basic colors -->
      <color name="green">#27D34D</color>
      <color name="blue">#2A91BD</color>
      <color name="orange">#FF9D2F</color>
      <color name="red">#FF432F</color>
  </resources>

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

注意：如果某些颜色和主题有关，那就独立出去写。

dimens.xml

像对待colors.xml一样对待dimens.xml文件与定义颜色调色板一样，你同时也应该定义一个空隙间隔和字体大小的“调色板”。一个好的例子，如下所示：

<resources>
    <!-- font sizes -->
    <dimen name="font_larger">22sp</dimen>
    <dimen name="font_large">18sp</dimen>
    <dimen name="font_normal">15sp</dimen>
    <dimen name="font_small">12sp</dimen>
    <!-- typical spacing between two views -->
    <dimen name="spacing_huge">40dp</dimen>
    <dimen name="spacing_large">24dp</dimen>
    <dimen name="spacing_normal">14dp</dimen>
    <dimen name="spacing_small">10dp</dimen>
    <dimen name="spacing_tiny">4dp</dimen>
    <!-- typical sizes of views -->
    <dimen name="button_height_tall">60dp</dimen>
    <dimen name="button_height_normal">40dp</dimen>
    <dimen name="button_height_short">32dp</dimen>
</resources>

strings.xml

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

styles.xml

在应用中对于大多数文本内容，最起码你应该有一个通用的style文件，例如：应用到TextView中:

<style name="ContentText">
    <item name="android:textSize">@dimen/font_normal</item>
    <item name="android:textColor">@color/basic_black</item>
</style>
<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/price"
    style="@style/ContentText"
    />

将一个大的style文件分割成多个文件，你可以有多个styles.xml 文件。Android SDK支持其它文件，styles这个文件名称并没有作用，起作用的是在文件里xml的<style>标签。因此你可以有多个style文件styles.xml、style_home.xml、style_item_details.xml、styles_forms.xml。不同于资源文件路径需要为系统构建起的有意义，在res/values目录下的文件可以任意命名。

layout中的id命名

命名模式为：view缩写_模块名_逻辑名，比如btn_main_search

版本统一规范

compileSdkVersion、minSdkVersion、targetSdkVersion以及项目中依赖第三方库的版本，不同的module及不同的开发人员都有不同的版本，所以需要一个统一版本规范的文件。具体可以参考博文:Android开发之版本统一规范

注释规范

类注释

每个类完成后应该有作者姓名和联系方式的注释，对自己的代码负责。

/**
 * <pre>
 *     author : Blankj
 *     e-mail : xxx@xx
 *     time   : 2017/03/07
 *     desc   : xxxx描述
 *     version: 1.0
 * </pre>
 */
 
public class WelcomeActivity {
       ...
}

具体可以在AS中自己配制，Settings → Editor → File and Code Templates → Includes → File Header，输入

/**
 * <pre>
 *     author : ${USER}
 *     e-mail : xxx@xx
 *     time   : ${YEAR}/${MONTH}/${DAY}
 *     desc   : 
 *     version: 1.0
 * </pre>
 */

这样便可在每次新建类的时候自动加上该头注释。

方法注释

每一个成员方法（包括自定义成员方法、覆盖方法、属性方法）的方法头都必须做方法头注释，在方法前一行输入/** + 回车或者设置Fix doc comment(Settings → Keymap → Fix doc comment)快捷键，AS便会帮你生成模板，我们只需要补全参数即可，如下所示。


/**
 * bitmap转byteArr
 * @param bitmap bitmap对象
 * @param format 格式
 * @return 字节数组
 */
public static byte[] bitmap2Bytes(Bitmap bitmap, CompressFormat format) {
    ......
    return baos.toByteArray();
}

块注释

以下示例注释都是OK的。

/*
 * This is                  
 * okay.                    
 */

 // And so  
 // is this.

/* Or you can
 * even do this. */

其他一些注释

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

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

其他的一些规范

合理布局，有效运用、、标签；
Activity和Fragment里面有许多重复的操作以及操作步骤，所以我们都需要提供一个BaseActivity和BaseFragment，让所有的Activity和Fragment都继承这个基类。
方法基本上都按照调用的先后顺序在各自区块中排列；
相关功能作为小区块放在一起（或者封装掉）；
当一个类有多个构造函数，或是多个同名方法，这些函数/方法应该按顺序出现在一起，中间不要放进其它函数/方法；
提取方法, 去除重复代码。对于必要的工具类抽取也很重要，这在以后的项目中是可以重用的。
一般不使用 System.out 输出，而是使用 Log 中的方法；
使用 BuildConfig.DEBUG 标记对 Log 进行封装，只在调试时输出重要信息，正式版不输出；
catch 块不得为空，至少应当将异常信息输出；
对于未完成的方法，使用 TODO 加以标记；

Android开发规范