开发规范

# 代码提交规范篇
1. 【推荐】代码提交应该短小而频繁，尽量避免单次提交大量代码。
说明：约束单次提交的范围有利于写出更加针对性的说明，也对代码审核更加友好。
反例：单次提交超过200+行的代码或20+的文件；只在休息的时候（午休、下班）提交代码；很难一句话说清楚这次提交的内容
2. 【强制】代码提交说明应该描述本次提交的具体内容，并带上适当的前缀
 * feat：新功能的说明
 * fix：修补bug的说明
 * docs：增加文档、注释
 * style： 调整代码格式（不影响任何代码逻辑的变动）
 * refactor：代码重构（既不是新增功能，也不是修改bug的代码变动）
 * test：增加测试
 * chore：构建过程或辅助工具的变动
 * 反例：无意义的说明比如“优化”、“bug fix”、“test”
3. 【推荐】代码提交说明字数控制在20字以内
4. 【推荐】代码提交说明无须以句号结尾

#### 为什么需要规范化代码提交？
1. 提供更多的历史信息，方便快速浏览
git log HEAD --pretty=format:%s
2. 可以过滤某些commit（比如功能性提交），便于快速查找信息
git log HEAD --pretty=format:%s | grep feat
3. 可以直接从commit生成某个release的变更日志
参考[conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)工具
4. 可以利用工具自动生成符合规范的commit message前缀
参考[commitizen](https://github.com/commitizen/cz-cli)工具
5. 对代码审核更加友好，通常直接review一个大的版本非常困难，而筛选出所有功能性提交（feat前缀）单独review则简单很多

#### 分支管理规范
1. 普通仓库
如果一个仓库的每个版本包含的功能列表是相对稳定的，一旦版本确定就不会随意增删功能，那么这就是一个普通类型的仓库，这类仓库通常功能相对简
单，只包含特定的服务/App。
这类仓库可以采用develop分支集成开发中的代码，并在该分支进行自动化构建测试。
![git](https://github.com/529523346/pics/blob/master/git_pic.png)
#### 分支策略
一共只存在两个永久分支：
* master
* origin/master分支的HEAD版本/tags反映了生产环境部署的最新代码。
下面几类分支都是临时性分支，有各自的生命周期：
   1. feature/* (zxf_v1.0.0)
   2. release/* (v1.0.0)
   3. hotfix/*  (zxf_v1.0.0)
* feature分支来自特定功能的开发、重构和优化，在适当的时候将合回develop分支。
* release分支从某个develop版本产生，当develop分支积累的代码适合做一次发布时，创建此分支进行测试和bug修复。
* hotfix分支来自线上产生的需紧急修复的bug。
* 这几类分支都有严格的创建流程和操作规范，下面将进行具体描述。
#### 项目操作流程
1. 创建项目：创建项目后，需要立即从master上创建永久性分支：develop ，
将此分支推入远程仓库origin/develop，master与develop两个永久分支的权限都需设置为只允许Merge不允许Push，即代码合并必须在git网页端发起Merge Request流程
2. 开发某个功能
 分支来源：origin/develop
 新建分支名称：feature/xxx
 xxx为本分支功能名称，不鼓励一个分支中包含多个功能。
 创建分支后切换到本分支进行开发和本地测试。
 准备提交QA测试是本分支结束的必要条件。
 发起Merge Request合并回：origin/develop，模块负责人/主管负责code review
 删除origin/feature/xxx分支
3. 完成某个版本提交测试
 分支来源：origin/develop
 新建分支名称：release/xxx
 xxx为本次发布的版本名称
4. QA测试中，修复BUG： 在release/xxx的分支上进行bug修改
 在本分支中，只能修改测试产生的相关bug，其他功能调整不可在本分支修改
5. 测试完成，准备上线：
 发起Merge Request将分支分别合并回：origin/master + origin/develop
 删除origin/release/xxx分支
 master分支添加tag：X.X.X，并在描述中说明本次版本的feature内容（可根据commit message生成）


# 编码规范篇
#### 为什么需要编码规范?


编码规范对于程序员而言尤为重要，有以下几个原因：

* 一个软件的生命周期中，80%的花费在于维护
* 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护
* 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码
* 如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品

####强制性规范:
* 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
* 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
* 类名使用UpperCamelCase 风格，必须遵从驼峰形式。
* 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。
* 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长例如：MAX_STOCK_COUNT。
* 抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类 命名以它要测试的类的名称开始。
* 杜绝不规范的英文缩写：AbstractClass 缩写成AbsClass；condition缩写成condi;此类随意缩写严重降低了代码的可阅读性。
* 如果使用到了设计模式，建议在类名中体现出具体的模式，例如：

`public class ComponentFactory`

`public class BufferStrategy`

`public class ScrollerProxy `
   
####关于Dao层或ArrayList的命名
* 插入：insert（推荐）或save
* 删除：delete
* 修改：update(推荐)或modify
* 查询单个对象：get
* 查询多个对象：list
* 实体类必须重载toString()方法，这样可以通过调用对象的toString()来排查问题。
* Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。
正例: `"test".equals(object);`
反例: `object.equals("test");`
* 避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
推荐规范：
* 集合初始化时，尽量指定集合初始值大小；ArrayList尽量使用ArrayList(int initialCapacity) 初始化 。
* 使用 entrySet 遍历 Map 类集合 KV，而不是 keySet 方式进行遍历
说明:keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出 key 所对应的 value。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效 率更高。如果是 JDK8，使用 Map.foreach 方法。
* 高度注意 Map 类集合 K/V 能不能存储 null 值的情况，如下表格:

集合类|Key|Value|Super|说明
  ------- | -------    |  ------- | -------
Hashtable|不允许为null|不允许为null|Dictionary| 线程安全
ConcurrentHashMap  | 不允许为null | 不允许为null | AbstractMap  | 分段锁技术
TreeMap    | 不允许为null | 允许为null  | AbstractMap|     线程不安全
HashMap    | 允许为null  | 允许为null  | AbstractMap  | 线程不安全
 
* 利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的 contains 方法进行遍历、对比、去重操作。
* 通过双重检查锁(double-checked locking)(在并发场景)实现延迟初始化的优 化问题隐患(可参考 The "Double-Checked Locking is Broken" Declaration),推荐问题 解决方案中较为简单一种(适用于 JDK5 及以上版本)，将目标属性声明为 volatile 型。  

 *反例*

```
class Foo {
    private Helper helper = null;
    
    public Helper getHelper() {
     if (helper == null) 
            synchronized(this) { 
                if (helper == null)
                    helper = new Helper(); 
            } 
            return helper; 
    } // other functions and members... 
     } 
```
应该为：

```
class Foo {
    private volatile static Helper helper = null;
    
    public Helper getHelper() {
     if (helper == null) 
            synchronized(this) { 
                if (helper == null)
                    helper = new Helper(); 
            } 
            return helper; 
    } // other functions and members... 
     } 
```

####Android代码规范
***代码：***  

* Activity 命名一律使用 模块名+Activity 的方式。例如，LoginActivity、SignupActivity；  
* Fragment 命名一律使用 模块名+Fragment 的方式；  
* 自定义View：Custom(建议)+功能名+View/ViewGroup(具体的组件名称)。例如：CustomImageScroller、CustomRatingBar。  
* Widget 小组件：ScanWidget、WeatherWidget。
* Dialog对话框：功能名+Dialog。例如：LoginDialog、ProgressDialog 
* 尽量在每一个Activity或类中加入TAG,方便我们查看Activity的信息，这里Android Studio提供了快捷方式logt方式即可快速生成当前类的常量。
* 对于使用Intent传递数据，声明一些Key的时候：
EXTRA_KEY_+具体Key名称，例如我们现在有一个人的名字和年龄要传那么首先定义：  
`public static final String EXTRA_KEY_PERSON_NAME="EXTRA_KEY_PERSON_NAME"`  
`public static final String EXTRA_KEY_PERSON_NAME="EXTRA_KEY_PERSON_AGE"`  
然后在具体的页面 `new Intent()`，依次传递进去值，这样写其实没什么问题；但是试想一下，如果你要调用的Activity是类似于一个工具性质或通用的Activity（图片选择器、登录、注册等等），这时候你要传递的key又很多，如果业务复杂的话，你应该会被这样冗余且不易阅读的代码直接搞崩溃掉。
所以最好的办法就是在你要调用Activity提供一个静态工厂方法，要知道静态工厂方法所带来的好处太多了，由于Activity是不允许通过new的方式来初始化的，所以静态工厂方法的好处在此就不那么明显，但是已经足够我们优化我们的代码了。举个例子，我们有一个笔记 NoteActivity，用于创建笔记和修改笔记

 ```
Idprivate static final String EXTRA_KEY_NOTE_ID ="EXTRA_KEY_NOTE_ID" ;//笔记 
private static final String EXTRA_KEY_NOTE_CONTENT ="EXTRA_KEY_NOTE_CONTENT" ;//笔记内容
private static final String EXTRA_KEY_NOTE_MODE ="EXTRA_KEY_NOTE_MODE" ;//笔记模式
//用于创建笔记  
public static void startForCreate(Context context, int noteId) {
    start(context, noteId, null, MODE_CREATE);
}
    //用于编辑笔记
public static void startForEdit(Context context, int noteId, String content) {
    start(context, noteId, content, MODE_UPDATE);
}  
public static void start(Context context, int noteId, String content, int mode) {  
    Intent starter = new Intent(context, TableShareListSettingActivity.class);
    starter.putExtra(EXTRA_KEY_NOTE_ID,noteId);
    starter.putExtra(EXTRA_KEY_NOTE_CONTENT,content);
    starter.putExtra(EXTRA_KEY_NOTE_CONTENT,mode);
    context.startActivity(starter);
}
 ```

通过以上方法，我们能够很好的解耦复杂的Activity之间的调用，再加上静态方法工厂方法名，代码可阅读行大大提高，最终我们看到的调用NoteActivity将会是很简洁的一段代码：  
`NoteActivity.startForCreate(this,noteId);`  
`NoteActivity.startForEdit(this,noteId,content);`   
此外，Android Studio工具中其实已经在Live Template中提供了这样的代码:简单的输入starter就可以快速地在当前的Activity中添加一个Intent的静态操作方法，这其实也说明了Android官方团队也鼓励我们这么做。
* 增加类注释

```
/**
 * @Title： 
 * @Description：
 * @Author：xuefeng.zhu
 * @Since：2020-03-22
 * @Version：1.0.0
 */
 ```

* 所有的常量加上注释，且功能相同的排放在一起，不同的进行换行；
* Activity中全局变量采用m开头+类名。例如，mTable、mPerson；
* Activity中的控件：m+模块名+控件类型名称。例如，mLoginEditText（mLoginEt）,mLoginTextView（mLoginTv）;
* 统一Activity中函数的排版规则也能提高我们的阅读性；列如店播的loginActivity函数排版：

```
 LoginActivity extends BindingBaseActivity{

     @Override
     protected int getLayoutId() {
         return R.layout.user_activity_login;
     }
 
     @Override
     protected LoginViewModel getViewModel() {
         return new LoginViewModel(getBinding(), getIntent());
     }
 
     @ClickTrace
     @Override
     public void onClick(View v) {
         super.onClick(v);
         int i = v.getId();
         if (i == R.id.wx_login_tv_layout) { //微信登录
             getBinding().getViewModel().authorize(new Wechat());
         } else if (i == R.id.pick_other_login_way_tv) { //选择其他登录方式
             getBinding().getViewModel().showLoginWayDialog(this);
         } else if (i == R.id.has_referrer_tv) { //我有推荐人
             requestRecommend();
         } else if (i == R.id.close_iv) {
             finish();
         }
     }

   @Override
   public String getEventCode(int viewId) {
        com.analysis.statistics.http.RequestParams params = new com.analysis.statistics.http.RequestParams();
        params.put(Constant.PAGE, "00100000000");
        if (viewId == R.id.has_referrer_tv) {
            params.put(Constant.ACTION_CODE, "008");
            params.put(Constant.Z_ACTION_CODE, "001");
        }
        //无子操作编码不上报埋点
        String zActionCode = params.get(Constant.Z_ACTION_CODE);
        if (TextUtils.isEmpty(zActionCode)) {
            return "";
        }
        String code = params.formJsonString();
        params.clear();
        return code;
    }     
 }
```

先是实现父类的getLayoutId方法，显示页面布局；之后返回当前页面的viewModel;再然后是页面的点击事件...最后才是页面埋点方法；

资源Res
* 按照资源的类型，分为以下几种  
***命名规则:控件Id命名：模块（module:goods)_功能（name)_控件缩写(tv)***  

| Resources Type | 命名规则
  ------- | -------    
| TextView | goods_name_tv  
| EditText | goods_name_et
| ImageView    | goods_name_iv
| Button   | goods_name_bt
| ListView | goods_name_lv
| GridView | goods_name_gv
| CheckBox | goods_name_cb
| RadioButton  | goods_name_rb
| LinearLayout | goods_name_ll
| RelativeLayout   | goods_name_rl
| FrameLayout  | goods_name_fl
| GridLayout   | goods_name_gv


#####Color资源命名,String资源命名
***命名规则:模块（module:user)_组件名_具体作用名***

  Color资源命名

| Resources Type | 命名规则
  ------- | -------    
| color    | 模块（module)_具体作用名_color。例 R.color.goods_login_name_color

 String资源命名

| Resources Type | 命名规则
  ------- | -------    
| string   | 具体功能。 例 R.string.user_hello

 Drawable资源命名

| Resources Type | 命名规则
  ------- | -------    
| launcher icon    | ic_launcher。例R.drawable.user_ic_launcher
| normal icon  | ic_具体模块_功能。例R.drawable.user_ic_audio_pause
| Toolbar icon | user_ic_ab_功能名。例如user_ic_ab_search
| selector | selector_模块_功能名。例如 user_selector_login_button
| shape    | shape_模块功能名状态。例如 R.drawable.user_shape_login_button_normal
 
##### Layout命名规则
 ***命名规则:模块（module:user)_功能名_具体作用名***

| Resources Type | 命名规则
  ------- | -------    
| activity | activity_模块名。例如 R.layout.activity_login
| fragment | fragment_模块名。例如 R.layout.fragment_login_layout_header
| include  | layout_模块名_功能名。例如 @layout/layout_login_bottom
| adapter  | adapter_item_模块名_功能名。例R.layout.adapter_item_simple_text
| dialog   | dialog_模块_功能名。例如 R.layout.dialog_time_picker
| list header  | header_模块_功能。例如 R.layout.header_main_top_ad
| list footer  | footer_模块_功能。例如 R.layout.footer_main_bottom_action
| widget   | widget_模块_功能。例如 R.layout.widget_app_clock

##### Menu资源命名
 ***命名规则:模块（module:user)_menu_功能名***

| Resources Type | 命名规则
  ------- | -------    
| menu | menu_模块名。例如 menu_login

##### MenuValues资源命名
 ***命名规则:模块（module:user)_功能名(login)_组件(color)***

| Resources Type | 命名规则
  ------- | -------    
| color    | 模块名_color。例如 user_login_text_color  
| dimens   | 模块名_dimens。例如 user_login_textsize_dimens  
| style    | 模块名_style。例如 user_login_text_style  
| themes   | 模块名_themes。例如 user_login_themes  

#### 代码规范插件安装
 * checkstyle简介  
 checkstyle是idea中的一个插件，可以很方便的帮我们检查java代码中的格式错误，它能够自动化代码规范检查过程，从而使得开发人员从这项重要，但是枯燥的任务中解脱出来。
 * 使用步骤  
   下载checkstyle插件。在最上方的菜单栏中找到File中的settings，plugins即是下载插件的地方，我们再点击下方的Browse repositories，在其中查找checkstyle，并点击install就可以等待下载成功了
   配置checkstyle文件。下载好之后我们需要重启idea来启用插件，然后在settings>>Editor>>Inspections中可以确认是否启用
   接着在settings>>Other settings>>checkstyles的Configration file最右边有一个加号，点击它来添加配置文件，配置文件在项目根目录，文件名：code_template

#### 总结：
其实代码规范只是一个Guideline，大家遵从规范的目的是为了提高开发效率，并且使得代码容易阅读且维护性高！