騰訊架構(gòu)師教你如何寫出Android規(guī)范文檔
作者：techlearn
一份合格的代碼不應(yīng)只滿足于實(shí)現(xiàn)功能, 更應(yīng)該遵循良好的規(guī)范. 遵循良好的代碼規(guī)范有利于:提升程序穩(wěn)定性, 減少代碼隱患, 降低故障率;增強(qiáng)可擴(kuò)展性, 大幅提高維護(hù)效率;統(tǒng)一標(biāo)準(zhǔn), 提升多人協(xié)作效率;方便新人快速上手, 在項(xiàng)目組人員發(fā)生變動(dòng)時(shí)保證項(xiàng)目進(jìn)度。
前言
一份合格的代碼不應(yīng)只滿足于實(shí)現(xiàn)功能, 更應(yīng)該遵循良好的規(guī)范. 遵循良好的代碼規(guī)范有利于:
- 提升程序穩(wěn)定性, 減少代碼隱患, 降低故障率;
- 增強(qiáng)可擴(kuò)展性, 大幅提高維護(hù)效率;
- 統(tǒng)一標(biāo)準(zhǔn), 提升多人協(xié)作效率;
- 方便新人快速上手, 在項(xiàng)目組人員發(fā)生變動(dòng)時(shí)保證項(xiàng)目進(jìn)度。
這里梳理一下Android開(kāi)發(fā)過(guò)程中需要注意的一些地方, 包括多個(gè)部分, 另外根據(jù)約束力強(qiáng)弱分為兩類:
- 強(qiáng)制: 如果不遵守會(huì)導(dǎo)致代碼嚴(yán)重混亂, 后期維護(hù)復(fù)雜, 甚至?xí)霈F(xiàn)嚴(yán)重bug;
- 推薦: 如果不遵守可能會(huì)導(dǎo)致代碼描述不清, 理解困難, 導(dǎo)致功能越多維護(hù)越難的問(wèn)題。
下面是規(guī)范正文
系統(tǒng)設(shè)計(jì)
強(qiáng)制：
- 不允許出現(xiàn)兩段相同的邏輯塊, 必須抽出為公共方法, 差異性使用參數(shù)控制, 避免修改時(shí)多處修改導(dǎo)致遺漏;
- 不允許出現(xiàn)兩段相同的處于同一邏輯組的復(fù)雜布局, 必須抽為單獨(dú)的include/merge;
- 不允許父類中出現(xiàn)子類具體方法, 如果需要的話可以父類定義抽象方法, 交由子類實(shí)現(xiàn);
- 不允許Activity內(nèi)多Fragment之間的直接溝通, 必須通過(guò)Activity中轉(zhuǎn)。
推薦：
- 推薦使用MVP或者M(jìn)VVM架構(gòu);
- 推薦使用Kotlin語(yǔ)言;
- 采用模塊分類方式替代文件類別方式, 方便快速查找模塊相關(guān)內(nèi)容, 例: LoginActivity/LoginPreenter/LoginHttpRequest/LoginBean/LoginAdapter等所屬同一登錄模塊的文件放入一個(gè)文件夾, 而不是所有activity放入一個(gè)文件夾, 所有adapter放入一個(gè)文件夾。
命名方式
強(qiáng)制：
- 不允許出現(xiàn)中文命名方式;
- java/kotlin文件使用大駝峰方式, 例: LoginActivity.kt, NewsAdapter.kt, NewsBean.java;
- layout/drawable/anim/style等resource文件使用小寫+下劃線的方式, 例: login_activity.xml, login_logo.png;
- 類定義使用大駝峰方式, 例: class LoginPresenter {}, class NewsBean {};
- 對(duì)象使用小駝峰方式, 例: LoginPresenter loginPresenter, NewsBean newsBean;
- 靜態(tài)常量使用全大寫+下劃線的方式, 例: public static final boolean IS_RELESAE = true;
- Kotlin使用的布局中的控件id必須使用小駝峰方式, 例: android:id="@+id/tvLogin"。
推薦：
- 文件/資源命名時(shí)采用 模塊+類型 的方式, 以便迅速查找相關(guān)內(nèi)容, 例如登錄頁(yè)面: LoginActivity.kt, login_activity.xml, login_logo.png, 網(wǎng)絡(luò)錯(cuò)誤, #f3f3f3
- java使用的布局中的id名建議使用小駝峰方式, 并且使用控件類型縮寫開(kāi)頭, 例: android:id="@+id/tvLogin", 附錄常用控件縮寫:
可見(jiàn)性
強(qiáng)制：
- 所有新定義的類/方法, 默認(rèn)寫成private, 只有在其他類需要引用時(shí)再看情況標(biāo)為public, protected, package-private;
推薦:
- java定義的父類中定義的方法如果子類重寫會(huì)導(dǎo)致問(wèn)題時(shí), 添加final關(guān)鍵字;
注釋相關(guān)
類/復(fù)雜或者不能從方法名字看出意圖的方法必須添加注釋, 當(dāng)類/方法添加注釋時(shí), 必須使用此類型注釋:
- /**
- * Created by XXX on 2019/6/19.
- * 描述此類作用, 邏輯復(fù)雜的說(shuō)明一下主要思路
- */
- public class LoginPresenter {
- /**
- * 用于進(jìn)行網(wǎng)絡(luò)請(qǐng)求
- * @params xxx XXX
- */
- public void doLoginRequest(...){}
- }
變量注釋不允許使用與類/方法一致的注釋形式;
方法注釋中不允許出現(xiàn)@params, @return的參數(shù)描述錯(cuò)誤的情況, 必須實(shí)時(shí)更新;
推薦：
- 一段邏輯建議使用/* */的方式;
- 方法/參數(shù)建議添加 @Nullable, @NotNull, @UiThread 等注解;
代碼風(fēng)格
- 此git目錄下同時(shí)存有 AndroidCodeStyleSetting.jar 配置文件, 用于AndroidStudio導(dǎo)入后按照統(tǒng)一風(fēng)格進(jìn)行代碼的格式化.
- 如果沒(méi)有編寫代碼時(shí)隨時(shí)格式化代碼的習(xí)慣, 可以在AndroidStudio版本控制提交窗口右側(cè)Before Commit中勾選Reformat code選項(xiàng).
Android基本組件
強(qiáng)制：
- Intent通信時(shí)不允許傳遞超過(guò)1M的數(shù)據(jù), 可以采用外部Presenter中轉(zhuǎn)或者EventBus傳遞的方式;
- Intent隱式啟動(dòng)時(shí)必須檢查目標(biāo)是否存在, 否則會(huì)出現(xiàn)目標(biāo)未找到崩潰: if (getPackageManager().resolveActivity(intent, PackageManager.MATCH_DEFAULT_ ONLY) != null);
- Activity/Service/BroadcastReceiver內(nèi)如果有耗時(shí)操作, 必須采用多線程進(jìn)行處理;
- 應(yīng)用內(nèi)部發(fā)送廣播時(shí), 只能使用LocalBroadcastManager.getInstance(this).sendBroadcast(intent), 不允許 context.sendBroadcast(intent), 避免外部應(yīng)用攔截;
- 不允許在Application中緩存數(shù)據(jù), 全局的共享數(shù)據(jù)可以使用某presenter存儲(chǔ), 或者使用SharedPreference讀寫;
- Activity或者Fragment中動(dòng)態(tài)注冊(cè)BroadCastReceiver時(shí)，registerReceiver和unregisterReceiver必須要成對(duì)出現(xiàn);
推薦：
- Activity#onPause/onStop中結(jié)合isFinishing的判斷來(lái)執(zhí)行資源的釋放, 必免放在執(zhí)行時(shí)機(jī)較晚的Activity#onDestroy()中執(zhí)行;
- 不要在Activity#onPause中執(zhí)行耗時(shí)操作, 這樣會(huì)導(dǎo)致界面跳轉(zhuǎn)卡頓, 可以放入Activity#onStop中執(zhí)行;
UI/布局
強(qiáng)制：
- 布局xml優(yōu)先使用ConstraintLayout, 可以保證無(wú)嵌套的情況下完成包括部分控件同時(shí)顯隱需求在內(nèi)的99%的布局要求;
- 不允許使用ScrollView包裹ListView/GridView/ExpandableListVIew等列表View, 復(fù)雜多項(xiàng)式列表可以使用多ItemType進(jìn)行處理;
推薦：
- 在Activity中顯示對(duì)話框或彈出浮層時(shí), 盡量使用DialogFragment, 而非Dialog/AlertDialog, 便于隨Activity生命周期管理彈窗的生命周期;
進(jìn)程/線程/消息推送
強(qiáng)制：
- 存在多進(jìn)程的情況時(shí), Application中的初始化代碼要根據(jù)進(jìn)程分別處理, 避免初始化不必要的業(yè)務(wù);
- 新建線程時(shí), 必須通過(guò)線程池的方式, 不允許采用new Thread()的方式;
- Activity/Fragment中使用Handler時(shí), 必須使用靜態(tài)內(nèi)部類+WeakReferences方式或者在onStop中調(diào)用handler.removeCallbacksAndMessages;
推薦：
- 多進(jìn)程間共享數(shù)據(jù)使用ContentProvider替代SharedPreferences#MODE_MULTI_PROCESS;
文件/數(shù)據(jù)庫(kù)
強(qiáng)制：
- 使用系統(tǒng)API獲取文件路徑, 避免手拼字符串, 例: android.os.Environment#getExternalStorageDirectory(), Context#getFilesDir(), 錯(cuò)誤示例: File file = new File("/mnt/sdcard/Download/Album", name);
- 當(dāng)使用外部存儲(chǔ)時(shí), 必須檢查外部存儲(chǔ)的可用性: Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
- 數(shù)據(jù)庫(kù)Cursor使用之后必須關(guān)閉, 以免內(nèi)存泄漏;
推薦：
SharedPreference僅存儲(chǔ)簡(jiǎn)單數(shù)據(jù)類型, 不要存儲(chǔ)復(fù)雜數(shù)據(jù), 如json數(shù)據(jù)/Bitmap編碼等;
SharedPreference提交數(shù)據(jù)時(shí), 盡量使用Editor#apply(), 而非Editor#commit();
圖片/動(dòng)畫
強(qiáng)制：
- 加載大圖時(shí)必須在子線程中處理, 否則會(huì)卡UI;
- 在Activity.onPause()/onStop()中關(guān)閉當(dāng)前activity正在執(zhí)行的動(dòng)畫;
推薦：
- Android圖片建議轉(zhuǎn)化為WebP格式, 可以減少APK體積;
- 動(dòng)畫盡量不要使用AnimationDrawable, 占用非常多內(nèi)存;
- 使用ARGB_565代替ARGB_888, 減少內(nèi)存占用;
- 當(dāng)Animation執(zhí)行結(jié)束時(shí), 調(diào)用View.clearAnimation()釋放相關(guān)資源;
安全性
強(qiáng)制：
- 上線包必須混淆;
- 加解密的秘鑰/鹽不允許硬編碼到代碼中, 以防反編譯獲取;
- Https處理時(shí)必須校驗(yàn)證書, 不允許直接接受任意證書;
- 使用Android的AES/DES/DESede加密算法時(shí), 不要使用默認(rèn)的加密模式ECB, 應(yīng)顯示指定使用CBC/CFB加密模式;
- 禁止把敏感信息打印到log中;
- 在應(yīng)用發(fā)布時(shí)必須確保android:debuggable為false;
- 必須利用X509TrustManager子類中的checkServerTrusted函數(shù)效驗(yàn)服務(wù)器端證書的合法性,
- 必須將android:allowbackup屬性設(shè)置為false, 防止adb backup導(dǎo)出應(yīng)用數(shù)據(jù)。
責(zé)任編輯：未麗燕
來(lái)源：
安卓巴士
