Android教程網
  1. 首頁
  2. Android 技術
  3. Android 手機
  4. Android 系統教程
  5. Android 游戲
 Android教程網 >> Android技術 >> Android開發 >> 關於android開發 >> 最全面的 Android 編碼規范指南,最全android

最全面的 Android 編碼規范指南,最全android

編輯:關於android開發

最全面的 Android 編碼規范指南,最全android


 

最全面的 Android 編碼規范指南

本文word文檔下載地址:http://pan.baidu.com/s/1bXT75O

1. 前言

這份文檔參考了 Google Java 編程風格規范和 Google 官方 Android 編碼風格規范。該文檔僅供參考,只要形成一個統一的風格,見量知其意就可。

1.1 術語說明

在本文檔中,除非另有說明:

1.2 指南說明本文檔中的示例代碼並不作為規范,僅供參考。

基本格式方面使用 AndroidStudio 默認模板即可(使用格式化快捷鍵處理後基本符合)。

2. 源文件基礎

2.1 文件名

源文件以其最頂層的類名來命名,大小寫敏感,文件擴展名為.java。

2.2 文件編碼:UTF-8

源文件編碼格式為 UTF-8。

2.3 特殊字符

2.3.1 空白字符

除了行結束符序列,ASCII水平空格字符(0×20,即空格)是源文件中唯一允許出現的空白字符,這意味著:

2.3.2 特殊轉義序列

對於具有特殊轉義序列的任何字符(\b, \t, \n, \f, \r, \”, \’及),我們使用它的轉義序列,而不是相應的八進制(比如\012)或Unicode(比如\u000a)轉義。

2.3.3 ASCII字符

對於剩余的非ASCII字符,是使用實際的Unicode字符(比如∞),還是使用等價的Unicode轉義符(比如\u221e),取決於哪個能讓代碼更易於閱讀和理解。

Tip:在使用Unicode轉義符或是一些實際的Unicode字符時,建議做些注釋給出解釋,這有助於別人閱讀和理解。

例如:

String unitAbbrev = "μs"; | 贊,即使沒有注釋也非常清晰

String unitAbbrev = "\u03bcs"; // "μs" | 允許,但沒有理由要這樣做

String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" | 允許,但這樣做顯得笨拙還容易出錯

String unitAbbrev = "\u03bcs"; | 很糟,讀者根本看不出這是什麼

return '\ufeff' + content; // byte order mark | Good,對於非打印字符,使用轉義,並在必要時寫上注釋

Tip:永遠不要由於害怕某些程序可能無法正確處理非ASCII字符而讓你的代碼可讀性變差。當程序無法正確處理非ASCII字符時,它自然無法正確運行, 你就會去fix這些問題的了。(言下之意就是大膽去用非ASCII字符,如果真的有需要的話)

3. 源文件結構

一個源文件包含(按順序地):

3.1 許可證或版權信息

如果一個文件包含許可證或版權信息,那麼它應當被放在文件最前面。

3.2 package語句

package 語句不換行,列限制(4.4節)並不適用於package語句。(即package語句寫在一行裡)

3.3 import語句

3.3.1 import不要使用通配符

即,不要出現類似這樣的import語句:import java.util.*;

3.3.2 不要換行

import語句不換行,列限制(4.4節)並不適用於import語句。(每個import語句獨立成行)

3.3.3 順序和間距

import語句可分為以下幾組,按照這個順序,每組由一個空行分隔:

3.4 類聲明

3.4.1 只有一個頂級

類聲明每個頂級類都在一個與它同名的源文件中(當然,還包含.java後綴)。
例外:package-info.java,該文件中可沒有package-info類。

3.4.2 類成員順序

類的成員順序對易學性有很大的影響,但這也不存在唯一的通用法則。不同的類對成員的排序可能是不同的。

最重要的一點,每個類應該以某種邏輯去排序它的成員,維護者應該要能解釋這種排序邏輯。比如, 新的方法不能總是習慣性地添加到類的結尾,因為這樣就是按時間順序而非某種邏輯來排序的。

3.4.2.1 區塊劃分

建議使用注釋將源文件分為明顯的區塊,區塊劃分如下

10. 異步任務回調方法區

11. 生命周期回調方法區(出去onCreate()方法)

12. 內部類聲明區

3.4.2.2 類成員排列通用規則

3.4.2.3 重載:永不分離

當一個類有多個構造函數,或是多個同名方法,這些函數/方法應該按順序出現在一起,中間不要放進其它函數/方法。

4. 格式術語

說明:塊狀結構(block-like construct)指的是一個類,方法或構造函數的主體。需要注意的是,數組初始化中的初始值可被選擇性地視為塊狀結構(4.8.3.1節)。

4.1 大括號

4.1.1 使用大括號(即使是可選的)

大括號與if, else, for, do, while語句一起使用,即使只有一條語句(或是空),也應該把大括號寫上。

4.1.2 非空塊:K & R 風格

  • ·對於非空塊和塊狀結構,大括號遵循 Kernighan 和 Ritchie 風格 (Egyptian brackets):
    • ·左大括號前不換行
    • ·左大括號後換行
    • ·右大括號前換行
    • 如果右大括號是一個語句、函數體或類的終止,則右大括號後換行; 否則不換行。

例如,如果右大括號後面是else或逗號,則不換行。

示例:

return new MyClass() {   

    @Override public void method() {       

        if (condition()) {

            try {

                something();

            } catch (ProblemException e) {

                recover();

            }

        }

    }

};

4.8.1節給出了enum類的一些例外。

4.1.3 空塊:可以用簡潔版本

一個空的塊狀結構裡什麼也不包含,大括號可以簡潔地寫成{},不需要換行。

例外:如果它是一個多塊語句的一部分(if/else 或 try/catch/finally) ,即使大括號內沒內容,右大括號也要換行。
示例:

void doNothing() {}

4.2 塊縮進:4個空格

每當開始一個新的塊,縮進增加4個空格,當塊結束時,縮進返回先前的縮進級別。縮進級別適用於代碼和注釋。(見4.1.2節中的代碼示例)

4.3 一行一個語句

每個語句後要換行。

4.4 列限制:80100

一個項目可以選擇一行80個字符或100個字符的列限制,除了下述例外,任何一行如果超過這個字符數限制,必須自動換行。

例外:

  • ·不可能滿足列限制的行(例如,Javadoc中的一個長URL,或是一個長的JSNI方法參考)。
  • ·package和import語句(見3.2節和3.3節)。
  • 注釋中那些可能被剪切並粘貼到shell中的命令行。

4.5 自動換行

術語說明:一般情況下,一行長代碼為了避免超出列限制(80或100個字符)而被分為多行,我們稱之為自動換行(line-wrapping)。我們並沒有全面,確定性的准則來決定在每一種情況下如何自動換行。很多時候,對於同一段代碼會有好幾種有效的自動換行方式。

Tip:提取方法或局部變量可以在不換行的情況下解決代碼過長的問題(是合理縮短命名長度吧)

4.5.1 從哪裡斷開

自動換行的基本准則是:更傾向於在更高的語法級別處斷開。

4.5.2 自動換行時縮進至少+8個空格

自動換行時,第一行後的每一行至少比第一行多縮進8個空格(注意:制表符不用於縮進。見2.3.1節)。當存在連續自動換行時,縮進可能會多縮進不只8個空格(語法元素存在多級時)。一般而言,兩個連續行使用相同的縮進當且僅當它們開始於同級語法元素。

第4.6.3水平對齊一節中指出,不鼓勵使用可變數目的空格來對齊前面行的符號。

4.6 空白

4.6.1 垂直空白

以下情況需要使用一個空行:

4.6.2 水平空白

除了語言需求和其它規則,並且除了文字,注釋和Javadoc用到單個空格,單個ASCII空格也出現在以下幾個地方:

Note:這個規則並不要求或禁止一行的開關或結尾需要額外的空格,只對內部空格做要求。

4.6.3 水平對齊:不做要求

術語說明:水平對齊指的是通過增加可變數量的空格來使某一行的字符與上一行的相應字符對齊。
這是允許的(而且在不少地方可以看到這樣的代碼),但Google編程風格對此不做要求。即使對於已經使用水平對齊的代碼,我們也不需要去保持這種風格。

以下示例先展示未對齊的代碼,然後是對齊的代碼:

private int x; // this is fine

private Color color; // this too

 

private int    x;         // permitted, but future edits

private Color  color;     // may leave it unaligned

Tip:對齊可增加代碼可讀性,但它為日後的維護帶來問題。考慮未來某個時候,我們需要修改一堆對齊的代碼中的一行。
這可能導致原本很漂亮的對齊代碼變得錯位。很可能它會提示你調整周圍代碼的空白來使這一堆代碼重新水平對齊(比如程序員想保持這種水平對齊的風格)。
這就會讓你做許多的無用功,增加了reviewer的工作並且可能導致更多的合並沖突。

4.7 用小括號來限定組:推薦

除非作者和reviewer都認為去掉小括號也不會使代碼被誤解,或是去掉小括號能讓代碼更易於閱讀,否則我們不應該去掉小括號。

我們沒有理由假設讀者能記住整個Java運算符優先級表。

4.8 具體結構

4.8.1 枚舉類

枚舉常量間用逗號隔開,換行可選。

沒有方法和文檔的枚舉類可寫成數組初始化的格式:

private enum Suit {

    CLUBS,

    HEARTS,

    SPADES,

    DIAMONDS

}

由於枚舉類也是一個類,因此所有適用於其它類的格式規則也適用於枚舉類。

4.8.2 變量聲明

4.8.2.1 每次只聲明一個變量

不要使用組合聲明,比如int a, b;。

4.8.2.2 需要時才聲明,並盡快進行初始化

不要在一個代碼塊的開頭把局部變量一次性都聲明了(這是c語言的做法),而是在第一次需要使用它時才聲明。 局部變量在聲明時最好就進行初始化,或者聲明後盡快進行初始化。

4.8.3 數組

4.8.3.1 數組初始化:可寫成塊狀結構

數組初始化可以寫成塊狀結構,比如,下面的寫法都是OK的:

new int[] {

        0, 1, 2, 3

}

new int[] {

        0,

        1,

        2,

        3

}

new int[] {

        0, 1,

        2, 3

}

new int[]

        {0, 1, 2, 3}

4.8.3.2 C風格的數組聲明

中括號是類型的一部分:String[] args, 而非 String args[]。

4.8.4 switch語句

術語說明:switch塊的大括號內是一個或多個語句組。
每個語句組包含一個或多個switch標簽(case FOO:或default:),後面跟著一條或多條語句。

4.8.4.1 縮進

與其它塊狀結構一致,switch塊中的內容縮進為2個空格。每個switch標簽後新起一行,再縮進2個空格,寫下一條或多條語句。

4.8.4.2 Fall-through:注釋

在一個switch塊內,每個語句組要麼通過break, continue, return或拋出異常來終止,要麼通過一條注釋來說明程序將繼續執行到下一個語句組, 任何能表達這個意思的注釋都是OK的(典型的是用// fall through)。這個特殊的注釋並不需要在最後一個語句組(一般是default)中出現。

示例:

switch (input) {

    case 1:

    case 2:

        prepareOneOrTwo();        // fall through

    case 3:

        handleOneTwoOrThree();

        break;

    default:

        handleLargeNumber(input);

}

4.8.4.3 default的情況要寫出來

每個switch語句都包含一個default語句組,即使它什麼代碼也不包含。

4.8.5 注解(Annotations)

注解緊跟在文檔塊後面,應用於類、方法和構造函數,一個注解獨占一行。這些換行不屬於自動換行(第4.5節,自動換行),因此縮進級別不變。

例如:

@Nullable public String getNameIfPresent() { … }

例外:單個的注解可以和簽名的第一行出現在同一行。

例如:

@Override public int hashCode() { … }應用於字段的注解緊隨文檔塊出現,應用於字段的多個注解允許與字段出現在同一行。

例如:

@Partial @Mock DataLoader loader;

參數和局部變量注解沒有特定規則。

4.8.6 注釋

4.8.6.1 塊注釋風格

塊注釋與其周圍的代碼在同一縮進級別。它們可以是/ … /風格,也可以是// …風格。對於多行的/ … /注釋,後續行必須從開始, 並且與前一行的對齊。

以下示例注釋都是OK的。

/** This is // And so /* Or you can

 *  okay. // is this. * even do this. */

 */

注釋不要封閉在由星號或其它字符繪制的框架裡。

Tip:在寫多行注釋時,如果你希望在必要時能重新換行(即注釋像段落風格一樣),那麼使用/ … /。

4.8.7 Modifiers

類和成員的modifiers如果存在,則按Java語言規范中推薦的順序出現。

public protected private abstract static final transient Volatile synchronized native strictfp

5. 命名約定

5.1 對所有標識符都通用的規則

標識符只能使用ASCII字母和數字,因此每個有效的標識符名稱都能匹配正則表達式\w+。

5.2 標識符類型的規則

5.2.1 包名

包名全部小寫,連續的單詞只是簡單地連接起來,不使用下劃線。

采用反域名命名規則,全部使用小寫字母。一級包名為com,二級包名為xx(可以是公司或則個人的隨便),三級包名根據應用進行命名,四級包名為模塊名或層級名。

例如:com.jiashuangkuaizi.kitchen

包名

此包中包含

com.xx.應用名稱縮寫.activity

頁面用到的Activity類 (activitie層級名用戶界面層)

com.xx.應用名稱縮寫.base

基礎共享的類

com.xx.應用名稱縮寫.adapter

頁面用到的Adapter類 (適配器的類)

com.xx.應用名稱縮寫.util

此包中包含:公共工具方法類(util模塊名)

com.xx.應用名稱縮寫.bean

下面可分:vo、po、dto 此包中包含:JavaBean類

com.xx.應用名稱縮寫.model

此包中包含:模型類

com.xx.應用名稱縮寫.db

數據庫操作類

com.xx.應用名稱縮寫.view (或者 com.xx.應用名稱縮寫.widget )

自定義的View類等

com.xx.應用名稱縮寫.service

Service服務

com.xx.應用名稱縮寫.receiver

BroadcastReceiver服務

注意:
如果項目采用MVP,所有M、V、P抽取出來的接口都放置在相應模塊的i包下,所有的實現都放置在相應模塊的impl下

5.2.2 類名

類名都以UpperCamelCase風格編寫。

類名通常是名詞或名詞短語,接口名稱有時可能是形容詞或形容詞短語。現在還沒有特定的規則或行之有效的約定來命名注解類型。

名詞,采用大駝峰命名法,盡量避免縮寫,除非該縮寫是眾所周知的, 比如HTML,URL,如果類名稱中包含單詞縮寫,則單詞縮寫的每個字母均應大寫。

描述

例如

Activity 類

Activity為後綴標識

歡迎頁面類WelcomeActivity

Adapter類

Adapter 為後綴標識

新聞詳情適配器 NewDetailAdapter

解析類

Parser為後綴標識

首頁解析類HomePosterParser

工具方法類

Util或Manager為後綴標識(與系統或第三方的Utils區分)或功能+Util

線程池管理類:ThreadPoolManager日志工具類:LogUtil(Logger也可)打印工具類:PrinterUtil

數據庫類

以DBHelper後綴標識

新聞數據庫:NewDBHelper

Service類

以Service為後綴標識

時間服務TimeServiceBroadcast

Receiver類

以Receiver為後綴標識

推送接收JPushReceiver

ContentProvider

以Provider為後綴標識

 

自定義的共享基礎類

以Base開頭

BaseActivity,BaseFragment

測試類的命名以它要測試的類的名稱開始,以Test結束。

例如:HashTest 或 HashIntegrationTest。

接口(interface):命名規則與類一樣采用大駝峰命名法,多以able或ible結尾,如

interface Runnable ;
interface Accessible。

注意:
如果項目采用MVP,所有Model、View、Presenter的接口都以I為前綴,不加後綴,其他的接口采用上述命名規則。

5.2.3 方法名

方法名都以 LowerCamelCase 風格編寫。

方法名通常是動詞或動詞短語。

方法

說明

initXX()

初始化相關方法,使用init為前綴標識,如初始化布局initView()

isXX() checkXX()

方法返回值為boolean型的請使用is或check為前綴標識

getXX()

返回某個值的方法,使用get為前綴標識

handleXX()

對數據進行處理的方法,盡量使用handle為前綴標識

displayXX()/showXX()

彈出提示框和提示信息,使用display/show為前綴標識

saveXX()

與保存數據相關的,使用save為前綴標識

resetXX()

對數據重組的,使用reset前綴標識

clearXX()

清除數據相關的

removeXXX()

清除數據相關的

drawXXX()

繪制數據或效果相關的,使用draw前綴標識

下劃線可能出現在JUnit測試方法名稱中用以分隔名稱的邏輯組件。一個典型的模式是:test_,例如testPop_emptyStack。

並不存在唯一正確的方式來命名測試方法。

5.2.4 常量名

常量名命名模式為CONSTANT_CASE,全部字母大寫,用下劃線分隔單詞。那,到底什麼算是一個常量?

每個常量都是一個靜態final字段,但不是所有靜態final字段都是常量。在決定一個字段是否是一個常量時,考慮它是否真的感覺像是一個常量。

例如,如果任何一個該實例的觀測狀態是可變的,則它幾乎肯定不會是一個常量。只是永遠不打算改變對象一般是不夠的,它要真的一直不變才能將它示為常量。

// Constants

static final int NUMBER = 5;

static final ImmutableListNAMES = ImmutableList.of("Ed", "Ann");

static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable

static final SomeMutableType[] EMPTY_ARRAY = {};

enum SomeEnum { ENUM_CONSTANT }

// Not constants

static String nonFinal = "non-final";

final String nonStatic = "non-static";

static final SetmutableCollection = new HashSet();

static final ImmutableSetmutableElements = ImmutableSet.of(mutable);

static final Logger logger = Logger.getLogger(MyClass.getName());

static final String[] nonEmptyArray = {"these", "can", "change"};

這些名字通常是名詞或名詞短語。

5.2.5 非常量字段名

非常量字段名以LowerCamelCase風格的基礎上改造為如下風格:

基本結構為scopeVariableNameType,

scope:范圍

非公有,非靜態字段命名以m開頭。

靜態字段命名以s開頭。

公有非靜態字段命名以p開頭。

公有靜態字段(全局變量)命名以g開頭。

public static final 字段(常量) 全部大寫,並用下劃線連起來。

例子:

public class MyClass { 

       public static final int SOME_CONSTANT = 42; 

       public int pField; 

       private static MyClass sSingleton; 

       int mPackagePrivate; 

       private int mPrivate; 

       protected int mProtected;

       public static int gField;

}

使用1字符前綴來表示作用范圍,1個字符的前綴必須小寫,前綴後面是由表意性強的一個單詞或多個單詞組成的名字,而且每個單詞的首寫字母大寫,其它字母小寫,這樣保證了對變量名能夠進行正確的斷句。

Type:類型

考慮到Android中使用很多UI控件,為避免控件和普通成員變量混淆以及更好達意,所有用來表示控件的成員變量統一加上控件縮寫作為後綴(文末附有縮寫表)。

對於普通變量一般不添加類型後綴,如果統一添加類型後綴,請參考文末的縮寫表。

用統一的量詞通過在結尾處放置一個量詞,就可創建更加統一的變量,它們更容易理解,也更容易搜索。

注意:如果項目中使用ButterKnife,則不添加m前綴,以LowerCamelCase風格命名。

例如,請使用 mCustomerStrFirst 和 mCustomerStrLast,而不要使用mFirstCustomerStr和mLastCustomerStr。

量詞列表:量詞後綴說明

First 一組變量中的第一個
Last 一組變量中的最後一個
Next 一組變量中的下一個變量
Prev 一組變量中的上一個
Cur 一組變量中的當前變量。

說明:

集合添加如下後綴:List、Map、Set

數組添加如下後綴:Arr

注意:所有的VO(值對象)統一采用標准的lowerCamelCase風格編寫,所有的DTO(數據傳輸對象)就按照接口文檔中定義的字段名編寫。

5.2.6 參數名

參數名以LowerCamelCase風格編寫

5.2.7 局部變量名

局部變量名以LowerCamelCase風格編寫,比起其它類型的名稱,局部變量名可以有更為寬松的縮寫。

雖然縮寫更寬松,但還是要避免用單字符進行命名,除了臨時變量和循環變量。

即使局部變量是final和不可改變的,也不應該把它示為常量,自然也不能用常量的規則去命名它。

臨時變量

臨時變量通常被取名為i,j,k,m和n,它們一般用於整型;c,d,e,它們一般用於字符型。 如: for (int i = 0; i < len ; i++),並且它和第一個單詞間沒有空格。

5.2.8 類型變量名

類型變量可用以下兩種風格之一進行命名:

  • 單個的大寫字母,後面可以跟一個數字(如:E, T, X, T2)。
  • 以類命名方式(5.2.2節),後面加個大寫的T(如:RequestT, FooBarT)。

5.2.9 資源文件命名規范

1. 資源布局文件(XML文件(layout布局文件)):

全部小寫,采用下劃線命名法
1) contentview 命名
必須以全部單詞小寫,單詞間以下劃線分割,使用名詞或名詞詞組。
所有Activity或Fragment的contentView必須與其類名對應,對應規則為:
將所有字母都轉為小寫,將類型和功能調換(也就是後綴變前綴)。
例如:activity_main.xml

2) Dialog命名:dialog_描述.xml
例如:dialog_hint.xml

3) PopupWindow命名:ppw_描述.xml
例如:ppw_info.xml

4) 列表項命名:item_描述.xml
例如:item_city.xml

5) 包含項命名:模塊_(位置)描述.xml
例如:activity_main_head.xml、activity_main_bottom.xml
注意:通用的包含項命名采用:項目名稱縮寫_描述.xml
例如:xxxx_title.xml
2. 資源文件(圖片drawable文件夾下):
全部小寫,采用下劃線命名法,加前綴區分
命名模式:可加後綴 _small 表示小圖, _big 表示大圖,邏輯名稱可由多個單詞加下劃線組成,采用以下規則:
用途_模塊名_邏輯名稱
用途_模塊名_顏色
用途_邏輯名稱
用途_顏色
說明:用途也指控件類型(具體見UI控件縮寫表)
例如:
btn_main_home.png 按鍵
divider_maket_white.png 分割線
ic_edit.png 圖標
bg_main.png 背景
btn_red.png 紅色按鍵
btn_red_big.png 紅色大按鍵
ic_head_small.png 小頭像
bg_input.png 輸入框背景
divider_white.png 白色分割線
如果有多種形態如按鈕等除外如 btn_xx.xml(selector)

名稱

功能

btn_xx

按鈕圖片使用btn_整體效果(selector)

btn_xx_normal

按鈕圖片使用btn_正常情況效果

btn_xx_pressed

按鈕圖片使用btn_點擊時候效果

btn_xx_focused

state_focused聚焦效果

btn_xx_disabled

state_enabled (false)不可用效果

btn_xx_checked

state_checked選中效果

btn_xx_selected

state_selected選中效果

btn_xx_hovered

state_hovered懸停效果

btn_xx_checkable

state_checkable可選效果

btn_xx_activated

state_activated激活的

btn_xx_windowfocused

state_window_focused

bg_head

背景圖片使用bg_功能_說明

def_search_cell

默認圖片使用def_功能_說明

ic_more_help

圖標圖片使用ic_功能_說明

seg_list_line

具有分隔特征的圖片使用seg_功能_說明

sel_ok

選擇圖標使用sel_功能_說明

注意:

使用AndroidStudio的插件SelectorChapek可以快速生成selector,前提是命名要規范。

3. 動畫文件(anim文件夾下):

全部小寫,采用下劃線命名法,加前綴區分。
具體動畫采用以下規則:
模塊名_邏輯名稱
邏輯名稱
refresh_progress.xml
market_cart_add.xml
market_cart_remove.xml
普通的tween動畫采用如下表格中的命名方式
// 前面為動畫的類型,後面為方向

動畫命名例子

規范寫法

fade_in

淡入

fade_out

淡出

push_down_in

從下方推入

push_down_out

從下方推出

push_left

推向左方

slide_in_from_top

從頭部滑動進入

zoom_enter

變形進入

slide_in

滑動進入

shrink_to_middle

中間縮小

4. values中name命名

類別

命名

示例

strings

strings的name命名使用下劃線命名法,采用以下規則:模塊名+邏輯名稱

main_menu_about 主菜單按鍵文字friend_title 好友模塊標題欄friend_dialog_del 好友刪除提示login_check_email 登錄驗證

dialog_title 彈出框標題

button_ok 確認鍵 loading 加載文字

 

colors

colors的name命名使用下劃線命名法,采用以下規則:模塊名+邏輯名稱 顏色

friend_info_bg friend_bg transparent gray

styles

styles的name命名使用 Camel命名法,采用以下規則:模塊名+邏輯名稱

main_tabBottom

5. layout中的id命名

命名模式為:view縮寫_view的邏輯名稱
使用 AndroidStudio 的插件 ButterKnife Zelezny,生成注解非常方便。
如果不使用 ButterKnife Zelezny,則建議使用 view 縮寫做後綴,如:username_tv(展示用戶名的TextView)

6. 編程實踐

6.1 @Override:能用則用

只要是合法的,就把@Override注解給用上。

6.2 捕獲的異常:不能忽視

除了下面的例子,對捕獲的異常不做響應是極少正確的。(典型的響應方式是打印日志,或者如果它被認為是不可能的,則把它當作一個 AssertionError 重新拋出。)

如果它確實是不需要在catch塊中做任何響應,需要做注釋加以說明(如下面的例子)。

try {

    int i = Integer.parseInt(response);

    return handleNumericResponse();

} catch (NumberFormatException ok) {

    // it's not numeric; that's fine, just continue

}

return handleTextResponse(response);

例外:在測試中,如果一個捕獲的異常被命名為expected,則它可以被不加注釋地忽略。下面是一種非常常見的情形,用以確保所測試的方法會拋出一個期望中的異常,因此在這裡就沒有必要加注釋。

try {

    emptyStack.pop();

    fail();

} catch (NoSuchElementException expected) {

}

6.3 靜態成員:使用類進行調用

使用類名調用靜態的類成員,而不是具體某個對象或表達式。

Foo aFoo = ...;

Foo.aStaticMethod(); // good

aFoo.aStaticMethod(); // bad

somethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4 Finalizers: 禁用

極少會去重載Object.finalize。

Tip:
不要使用finalize。如果你非要使用它,請先仔細閱讀和理解Effective Java 第7條款:”Avoid Finalizers”,然後不要使用它。

7. Javadoc

7.1 格式

7.1.1 一般形式

Javadoc塊的基本格式如下所示:

/**

* Multiple lines of Javadoc text are written here,

* wrapped normally...

*/

 public int method(String p1) { ... }

或者是以下單行形式:

/** An especially short bit of Javadoc. */

基本格式總是OK的。當整個Javadoc塊能容納於一行時(且沒有Javadoc標記@XXX),可以使用單行形式。

7.1.2 段落

空行(即,只包含最左側星號的行)會出現在段落之間和Javadoc標記(@XXX)之前(如果有的話)。

除了第一個段落,每個段落第一個單詞前都有標簽<p>,並且它和第一個單詞間沒有空格。

7.1.3 Javadoc標記

標准的Javadoc標記按以下順序出現:@param, @return, @throws, @deprecated,

前面這4種標記如果出現,描述都不能為空。 當描述無法在一行中容納,連續行需要至少再縮進4個空格。

7.2 摘要片段

每個類或成員的Javadoc以一個簡短的摘要片段開始。這個片段是非常重要的,在某些情況下,它是唯一出現的文本,比如在類和方法索引中。

這只是一個小片段,可以是一個名詞短語或動詞短語,但不是一個完整的句子。它不會以A {@code Foo} is a…或This method returns…開頭,它也不會是一個完整的祈使句,如Save the record…。然而,由於開頭大寫及被加了標點,它看起來就像是個完整的句子。

Tip:
一個常見的錯誤是把簡單的Javadoc寫成 /** @return the customer ID */,這是不正確的。它應該寫成/** Returns the customer ID. */。

7.3 哪裡需要使用Javadoc

至少在每個public類及它的每個public和protected成員處使用Javadoc,以下是一些例外:

7.3.1 例外:不言自明的方法

對於簡單明顯的方法如getFoo,Javadoc是可選的(即,是可以不寫的)。這種情況下除了寫”Returns the foo”,確實也沒有什麼值得寫了。

單元測試類中的測試方法可能是不言自明的最常見例子了,我們通常可以從這些方法的描述性命名中知道它是干什麼的,因此不需要額外的文檔說明。

Tip:
如果有一些相關信息是需要讀者了解的,那麼以上的例外不應作為忽視這些信息的理由。例如,對於方法名getCanonicalName,

就不應該忽視文檔說明,因為讀者很可能不知道詞語canonical name指的是什麼。

7.3.2 例外:重載

如果一個方法重載了超類中的方法,那麼Javadoc並非必需的。

7.3.3 可選的Javadoc

對於包外不可見的類和方法,如有需要,也是要使用Javadoc的。如果一個注釋是用來定義一個類,方法,字段的整體目的或行為,那麼這個注釋應該寫成Javadoc,這樣更統一更友好。

附錄:

表1 UI控件縮寫表

控件

縮寫

例子

LinearLayout

ll

llFriend或者mFriendLL

RelativeLayout

rl

rlMessage或mMessageRL

FrameLayout

fl

flCart或mCartFL

TableLayout

tl

tlTab或mTabTL

Button

btn

btnHome或mHomeBtn

ImageButton

ibtn

btnPlay或mPlayIBtn

TextView

tv

tvName或mNameTV

EditText

et

etName或mNameET

ListView

lv

lvCart或mCartLV

ImageView

iv

ivHead或mHeadIV

GridView

gv

gvPhoto或mPhotoGV

表2 常見的英文單詞縮寫:

名稱

縮寫

icon

ic (主要用在app的圖標)

color

cl(主要用於顏色值)

divider

di(主要用於分隔線,不僅包括Listview中的divider,還包括普通布局中的線)

selector

sl(主要用於某一view多種狀態,不僅包括Listview中的selector,還包括按鈕的selector)

average

avg

background

bg(主要用於布局和子布局的背景)

buffer

buf

control

ctrl

delete

del

document

doc

error

err

escape

esc

increment

inc

infomation

info

initial

init

image

img

Internationalization

I18N

length

len

library

lib

message

msg

password

pwd

position

pos

server

srv

string

str

temp

tmp

window

wnd(win)

程序中使用單詞縮寫原則:不要用縮寫,除非該縮寫是約定俗成的。

 

  1. 上一頁:
  2. 下一頁:
熱門文章
閱讀排行版
Copyright © Android教程網 All Rights Reserved