前言

由于開源項目的不斷增多康愤，我們的開發(fā)效率也得到了極大的提升，但是開源項目往往不能夠完全的match我們的需求舶吗，我們可能只是依賴其中的部分功能征冷，但是為此我們需要將一堆臃腫的代碼帶入到我們的項目中，為了解決這個問題誓琼，需要我們能夠很好地理解源碼检激，然后將我們需要的核心功能，從代碼中將其抽離出來腹侣，來適應(yīng)我們的項目叔收，而我們作為一個開源項目作者，作為一個負責的開源項目的作者筐带，就要求我們要能夠?qū)懗鲆?guī)范易懂今穿，便于閱讀的代碼，因此需要我們有規(guī)范的代碼命名規(guī)范伦籍，整潔的代碼規(guī)格蓝晒，同時擁有良好的文檔，為了方便開發(fā)者的使用帖鸦，我們還需要有良好的README來說明我們的項可以實現(xiàn)的功能芝薇，項目可能會出現(xiàn)一個平臺兼容性上的問題，或者是使用上的一些問題作儿，因此需要我們提供一個FAQ來幫助開發(fā)者解決一些粒度較大的問題洛二，對于每一次的功能迭代，版本更新攻锰，我們都需要提供版本更新說明晾嘶。

代碼命名規(guī)范

• 基本命名規(guī)范
  • 代碼中的命名均不能以下劃線或美元符號開始,也不能以下劃線或美元符號結(jié)束
  • 代碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式
  • 杜絕完全不規(guī)范的縮寫,避免望文不知義
• 包名
  • 包名為小寫
  • 點分隔符之間有且僅有一個自然語義的英語單詞，包名中單詞統(tǒng)一使用單數(shù)形式
• 類名
  • 類名必須是一個名詞娶吞，每個單詞首字母大寫垒迂。除了約定俗成的縮寫，盡量使用完整單詞
  • 實現(xiàn)類如果和接口區(qū)分妒蛇，請在接口名后加Impl
  • 抽象類命名使用Abstract或Base開頭
  • 異常類命名使用Exception結(jié)尾
  • 測試類命名以它要測試的類的名稱開始,以Test結(jié)尾
  • 如果使用到了設(shè)計模式机断，建議在類名中體現(xiàn)出具體模式楷拳，有利于閱讀者快速理解架構(gòu)設(shè)計思想
  • 枚舉類名建議帶上Enum后綴
• 方法名
  • 動詞或動詞+名詞
  • 采用駝峰命名方式，第一個單詞首字母小寫吏奸，其它單詞首字母大寫
• 變量名
  • 采用駝峰命名方式欢揖，首字母小寫，其后單詞的首字母大寫
  • 內(nèi)部使用的變量加m前綴
  • 靜態(tài)變量加s前綴
  • 控件名不需要和 id 名一致奋蔚，采取統(tǒng)一的縮寫前綴
• 常量名
  • 使用static final前綴她混，全部大寫，單詞間用下劃線隔開泊碑，并且指出完整含義
  • 不推薦使用枚舉产上，推薦在接口中定義常量字段
• 類成員位置順序：（類中順序按如下自頂向下）
  • 靜態(tài)常量
  • 靜態(tài)變量
  • 成員變量
  • 構(gòu)造方法
  • 成員方法
  • 靜態(tài)類方法
  • 內(nèi)部類以及內(nèi)部接口

代碼規(guī)格

流程控制

• 嵌套For/If/Try最大深度3
• 在if/else/for/while/do語句中必須用"{"和"}"括起來，避免引起沒必要的錯誤
• 對于多個的if/else 盡量把高概率匹配的放在前面蛾狗，提高性能
• 循環(huán)語句：盡量不要改變循環(huán)變量的值
• switch語句：對于多分支語句，建議使用switch語句仪媒，每個條件都要加break沉桌，在每一個switch塊內(nèi)，都必須包含一個default語句并放在最后算吩，即使它什么代碼也沒有

空行以及換行

垂直

單行空行在以下情況使用

• 類成員間需要空行隔開：例如成員變量留凭、構(gòu)造函數(shù)、成員函數(shù)偎巢、內(nèi)部類蔼夜、靜態(tài)初始化語句塊、實例初始化語句塊
• 成員變量之間的空白行不是必需的压昼。一般多個成員變量中間的空行求冷，是為了對成員變量做邏輯上的分組
• 在函數(shù)內(nèi)部，根據(jù)代碼邏輯分組的需要窍霞，設(shè)置空白行作為間隔
• 類的第一個成員之前匠题，或者最后一個成員結(jié)束之后，用空行間隔（可選）
• 單空行時使用多行空行是允許的但金，但是不要求也不推薦

水平

• 使用Tab進行控制韭山，推薦使用Android Studio默認的規(guī)范

字符編碼

一律使用utf8編碼

• String：String.getBytes()編碼統(tǒng)一使用utf-8，代碼文件編碼統(tǒng)一使用UTF-8
• URL編碼：請使用URLEncoder. encode(s, “utf-8”)方法

XML規(guī)則

資源命名規(guī)則

• 基本命名規(guī)范
  • 命名中單詞均采用小寫
  • 單詞之間采用下劃線分割
• layout xml資源命名
  • activity或fragment對應(yīng)的layout資源冷溃，一級標識為activity或fragment钱磅，例如：activity_media_picker.xml
  • 對于模塊資源，一級標示資源類型似枕，二級標示業(yè)務(wù)類型盖淡，比如：view_login_xxx.xml
  • 全局共享的資源：二級前綴可省略或使用app，例如：view_app_xxx.xml
  • listview或recycleview的item菠净，一級標識為item例如：item_xxx.xml
• drawable目錄的資源：（包含圖片以及xml）
  • 現(xiàn)在臨時放置在這個文件夾下的圖片禁舷，后面需要刪掉彪杉，命名為 tmp_XXXXX
  • xml 定義的 drawable 資源放置在這里
  • 其他正式要用的圖片，主要放置在 drawable-xhdpi 文件當中，其他需要適配的圖片文件自行放置在其他對應(yīng)的目錄下面
  • 多個模塊公用的圖標命名為 ic_XXXX，背景圖片命名為 bg_XXXX
  • 具體模塊單獨使用的圖片命名為 modulename_XXXX (如 userpage_XXXX)
  • selector 對應(yīng)的 xml 命名為 selector_XXXX
  • shape 對應(yīng)的 xml 命名為 shape_XXXX
  • 文件名最好能描述內(nèi)容信息铐达，命名模板property(屬性)_function(功能)_color/size（顏色/大小)_state.png凳宙，例如ic_switch_white_on.png
• colors
  • 通用的顏色直接使用名稱，如red妆艘，green等
  • 部分通用顏色，可以直接添加數(shù)字，如灰色（gray_aa, gray_f1）
  • 根據(jù)頁面模塊分組谱轨，注釋說明，空行隔開
  • 具體頁面相關(guān)的顏色吠谢，前面帶上頁面邏輯相關(guān)的名稱土童。例如login_btn_gray_666666，對于已有色彩采用間接引用工坊，不存在直接引用16進制顏色代碼
• dimens
  • 通用的半徑献汗、文字大小，可以分別定義成 radius_4dp王污，text_15sp等等
  • 其它和具體業(yè)務(wù)邏輯相關(guān)的罢吃，前帶上頁面邏輯相關(guān)的名稱
  • 對于已經(jīng)存在的尺寸采用間接引用

ID命名規(guī)則

• 統(tǒng)一使用前綴表明類型，比如btn_xxx昭齐，僅在布局使用的控件（不在代碼中使用）尿招，id使用layout_xxx前綴
• 命名單詞均采用小寫，通過下劃線分隔
• 命名二級標識頁面模塊阱驾，例如btn_login_login
• 縮寫前綴列表（歡迎補充）,自定義控件使用字母縮寫

Gradle規(guī)范

build.gradle(Project:ProjectName)規(guī)范

buildscript代碼塊

• 在dependencies聲明android gradle plugin的版本為最新版本（只需要保證二級版本為最新版）就谜，例如：

classpath 'com.android.tools.build:gradle:2.x.x'

build.gradle(Module:app)規(guī)范

編譯相關(guān)規(guī)范

• sdk版本號以及構(gòu)建工具版本使用最新的release版本

 compileSdkVersion 2x
 buildToolsVersion "2x.0.0"

• 設(shè)置代碼的編譯版本為1.7，使編譯出的包更通用

 compileOptions { 
        sourceCompatibility JavaVersion.VERSION_1_7 
        targetCompatibility JavaVersion.VERSION_1_7
 }

defaultConfig代碼塊規(guī)范

• targetSdkVersion里覆，同compileSdkVersion版本
• minSdkVersion 指定成11吁伺，android 4.0，原則上不支持4.0以下系統(tǒng)
• ndk無硬性規(guī)定租谈，非特殊的情況篮奄，只需在lib目錄中保留arm架構(gòu)的so庫

signingConfigs簽名規(guī)范

debug版本使用默認設(shè)置，release版本的簽名文件不得出現(xiàn)硬編碼密碼在build.gradle文件中割去，請將storePassword窟却、keyAlias以及keyPassword密碼放在properties文件中便于管理，示例：

signingConfigs {
    debug {
       storeFile file('debug.keystore')
    }
    release {
       // keystore
       storeFile file('release.keystore')

       // keys
       Properties properties = loadProperties('release.properties')

       storePassword properties.get('storepassword')
       keyAlias properties.get('keyalias')
       keyPassword properties.get('keypassword')
   }
}
 

buildTypes代碼塊規(guī)范

• shrinkResources 是否取消無效資源呻逆，去除無效資源有利用減少包大小夸赫，但會減慢編譯速度,建議在release版本中開啟
• minifyEnabled在混淆時去除代碼中無用的內(nèi)容，建議在release中開啟咖城，包含插件的項目中不允許開啟此選項
• zipAlignEnabled 資源包對齊茬腿，可提升執(zhí)行速度呼奢，減少內(nèi)存消耗，release模式下必須打開

dependencies代碼塊規(guī)范

• 為規(guī)避庫沖突切平，請使用遠程依賴的模式握础，指定groupId、artifactid以及版本號
• 需要使用本地依賴的情況悴品，請通過compile files逐個指定文件名禀综，不允許通過compile fileTree指定文件夾
• 本地依賴包需指定groudId，artifactId以及版本號苔严，例如com.facebook.fresco-fresco-0.8.1.jar
• 如無必要定枷，勿增實體：如果你的app沒有support，multi包需求届氢，請勿添加依賴
• exclude android庫欠窒，例如：exclude support包
• 盡可能使用lib，避免module依賴退子，獨立工程可以通過aar或mvn方式導(dǎo)入贱迟；原因：
  • rebuild成本過大
  • 構(gòu)建工具版本混亂
  • 未來涉及插件化非DSL腳本時，復(fù)雜度幾何上升

版本管理規(guī)范

• 使用最新的二級動態(tài)版本
• 使用ext拓展絮供，統(tǒng)一定義版本號
• 為提高可讀性，建議將名稱改為小寫縮寫茶敏，例如

ext {
    target_sdk_version = 24
}

權(quán)限規(guī)范

盡量避免Android 6.0敏感規(guī)范壤靶，例如：

• 手機狀態(tài)
• 位置信息（建議使用服務(wù)端IP定位）
• 讀寫SD卡（優(yōu)先使用拓展目錄）

JavaDoc規(guī)范

遵循原則

• 每個開放給用戶的函數(shù)/類，必須在文檔中
• 準確描述其中每個參數(shù)/成員的取值
• 僅用于內(nèi)部的函數(shù)/類惊搏，不要在文檔中暴露給用戶（可以另編簡要的開發(fā)者文檔作為記錄）
• 對于描述贮乳，盡可能的詳細，全面

具體實施

• 類的描述

  • 類的作用
  • 使用樣例

• 接口/抽象類

  • 作用
  • 框架提供的實現(xiàn)

• 方法的描述

  • 傳遞參數(shù)的類型恬惯，含義
  • 返回值的類型向拆，含義
  • 傳遞參數(shù)值的范圍對于程序執(zhí)行的影響
  • 方法產(chǎn)生的作用

README書寫規(guī)范

• 框架的集成方式
• 簡要的Getting Started（入門）或者一個詳細些的Tutorial（教程）
• 對于常用或者暴露給用戶的所有接口的Example（使用實例）

FAQ規(guī)范

• 去解答一些大尺度、共性的疑問
• 不要將一些小的問題也都類似單個函數(shù)的使用等加入進來

版本更新聲明

• 新增功能
• 解決問題