Android教程網 >> Android技術 >> 關於Android編程 >> Android編程規范V1.0

Android編程規范V1.0

編輯：關於Android編程

本文章是根據眾多公司的編程規范整理而成，如果錯誤，還請指出。

Android編程規范

編寫人

趙凱強

日期

2014-8-5

審核人

日期

批准人

日期

修改記錄（REVISION CHART）

版本

作者

修改描述

修改日期

1.0

趙凱強

初稿

2014-8-5

1.概述

1.1目的與概述

本文提供一整套編寫高效可靠的android代碼的標准、約定和指南。它們以安全可靠的軟件工程原則為基礎，使代碼易於理解、維護和增強。而且，通過遵循這些程序設計標准，你作為一個 Java 或者android 軟件開發者的生產效率會有顯著提高。經驗證明，若從一開始就花時間編寫高質量的代碼，則在軟件開發階段，對代碼的修改要容易很多。最後，遵循一套通用的程序設計標准將帶來更大的一致性，使軟件開發團隊的效率明顯提高。

1.2適用對象

1) Android開發工程師

2) Java開發工程師

1.3參考資料

Ø RUP2000中文版的《Java編程指南》

Ø Draft JavaCoding Standard Doug Lea

Ø Javasoft codingstandards

Ø TheInfospheres Java Coding Standard

1.4整體原則

原則(優先級從上到下遞減)

約定

便於閱讀

縮進

適當地增加括號

折行

行寬限制

與工具集成

對JavaDoc的注釋支持

Eclipse的模板文件及配置

便於調試

一行一條語句

便於寫作

注釋與語句不同行

減少重復

同樣的內容不在多處重復

2.Android編程規范

2.1命名規范

2.1.1命名的基本原則

在面向對象編程中，對於類，對象，方法，變量等方面的命名是非常有技巧的。比如，大小寫的區分，使用不同字母開頭等等。但究其本，追其源，在為一個資源命命名的時候，應該本著描述性和唯一性這兩大特征來命名，才能保證資源之間不沖突，並且每一個都便於記憶。

命名的一個基本原則是：使名稱足夠長以便有一定的意義，並且足夠短以避免冗長。

2.1.2通用的命名約定

Ø 采用該領域的術語。如果用戶稱他們的“客戶” (clients) 為“顧客” (customer)，那麼就采用術語 Customer 來命名這個類，而不用 Client。

Ø 注意大小寫。常量的字母全部大寫，單詞之間用一個下劃線字符“_”進行分隔。除常量外的命名采用大小寫混合，提高名字的可讀性。一般變量采用小寫字母，但是類和接口的名字的首字母，以及任何中間單詞的首字母應該大寫。這個命名規則也就是通常意義上的駝峰標識命名法。

Ø 使用可以准確說明的英文描述符。例如，采用類似firstName或CorporateCustomer這樣的名字。雖然象 x1，y1這樣的名字很簡短，輸入起來容易，但是我們難以知道它們代表什麼、結果是什麼含義，因而使代碼難以理解、維護和改進。

下面是通用的命名規范

標識符類型

命名規則

Examples

Packages

每一個包的名稱總是小寫，規則采用公司域名倒置，然後加上包的功能名。

com.baidu.map

Classes

類名必須是名詞，首字母大寫，采用駝峰命名法。類名應該簡單清晰。

class User;
class UpdateInfo;

Interfaces

同類名規則。

interface RasterDelegate;

Methods

方法應該是動詞，或以動詞開始的動賓結構短語，首字母小寫，采用駝峰命名法。

runFast();
getBackground();

Variables

變量名應該短而准確並便於記憶。首字母小寫，采用駝峰命名法。除了臨時使用的如循環變量等以外，不要使用單字符的變量名。對於使用單字符的臨時變量名，建議循環變量名用i,j,k，n表示整數。

Int i;

char c;

float myWidth;

Constants

全部大寫，單詞之間用下劃線分隔。

static final int MIN_WIDTH = 4;

2.1.3非強制的命名規范

類型

規則

例

抽象類

以Abstract開始

AbstractDjinn, AbstractCat, AbstractClass, AbstractPlayer

Factory類

以Factory結束

DjinnFactory, CatFactory, ClassFactory, PlayerFactor

Exception

以Exception結束

DjinnException, CatException, ClassException, PlayerException

Interface

以Interface結束或加-able後綴

DjinnInterface, CatInterface, Runnable, RemoteLoadable

2.2格式規范

2.2.1括號

在表達式、方法調用及方法聲明中圓括號“(”後及“)”前不應該有空格。

2.2.2縮進

一種提高代碼可讀性的方法是給代碼分段，換句話說，就是在代碼塊內讓代碼縮進。所有在括號{和}之內的代碼，構成一個塊。基本思想是，塊內的代碼都應統一地縮進去一個單位。

同級之間應該在同一個縮進位置。在下一級與上一級之間需要縮進。縮進單位默認為4個空格，即一個Tab鍵的距離。

2.2.3空白行

在代碼中加入幾個空行，將代碼分為一些小的、容易理解的部分，可以使它更加可讀。建議采用一個空行來分隔代碼的邏輯組，例如控制結構；采用兩個空行來分隔方法定義。沒有空白的代碼很難讀，很難理解。

下列情況下，一般需要寫入空白行：

Ø 包和引入之間加一個空行

Ø 不同可見性的變量定義之間加一個空行

Ø 方法定義之間加一個空行

Ø 不同可見性的方法組定義之間多加一個空行

2.2.4空格

Ø 關鍵字與其後緊挨的括號之間應有一個空格進行分隔。

Ø 參數列表的逗號之後應有一個空格進行分隔。

Ø 大括號開始之前應有一個空格進行分隔。

Ø 所有的二元操作符的前後均應有一個空格，二元操作符的例子有加號，除號，等於符號，賦值符號等。

Ø for的每一個語句之間應有空格，即for (expr1; expr2; expr3) 或者 for(expr1 : expr2)

Ø 強制類型轉換的括號之後應有一個空格。

雖然添加空格的情況很多，但是不要擔心，如果你是使用Eclipse開發的話，使用Shift+Ctrl+F快捷鍵，可以把代碼快速格式化。

2.2.5行寬

行寬不得超過最大行寬，超過最大行寬就需要折行，最大行寬為80。

行寬超過最大行寬往往需要用橫向滾動條，影響閱讀，而最大行寬之內的字符數在大多數閱讀器中均能方便地進行閱讀及打印。

2.3注釋規范

除Get,Set，構造析構等極其明白易懂的函數外，函數應當加上注釋。個別函數參數或返回值有約定時，應給出注釋說明。

函數體超過20行，應當在核心思想處給出注釋。

2.3.1注釋風格

注釋語句類型

用法

示例

文檔注釋

在接口、類、方法和字段聲明之前緊靠它們的位置用文檔注釋進行說明。文檔注釋由javadoc處理，為一個類生成外部注釋文檔。

/**

Customer（顧客）顧客是指作為我們的服務及產品的銷售對象的任何個人或組織。

@author S.W. Ambler

C語言風格注釋

采用 C 語言風格的注釋語句將無用的代碼注釋掉。保留這些代碼是因為用戶可能改變想法，或者只是想在調試中暫時不執行這些代碼。

這部分代碼已被它前面的代碼替代，所以於 1999 年6 月 4 日被 B. Gustafsson注釋掉。如果兩年之後仍未用這些代碼，將其刪除。

. . . （源代碼）

單行注釋

在方法內部采用單行注釋語句對業務邏輯、代碼片段和臨時變量聲明進行說明。

// 因為讓利活動

// 發貨單 5% 的折扣。

2.3.2常見Javadoc注釋標記

標記

用於

目的

@author name

類、

接口

說明特定某一段程序代碼的作者。

@deprecated

類、

方法

說明該類的應用程序編程接口 (API) 已被廢棄，因此應不再使用。

@exception name description

方法

說明由方法發出的異常。一個異常采用一個標記，並要給出異常的完整類名。

@param name description

方法

用來說明傳遞給一個方法的參數，其中包括參數的類型/類和用法。每個參數各有一個標記。

@return description

方法

若方法有返回值，對該返回值進行說明。

@see ClassName

類、接口、方法、字段

在文檔中生成指向特定類的超文本鏈接。可以並且應該采用完全合法的類名。

@see ClassName#memberfunctionName

類、接口、方法、字段

在文檔中生成指向特定方法的超文本鏈接。可以並且應該采用完全合法的類名。

@version text

類、接口

說明特定一段代碼的版本信息。

2.3.3通用注釋規范

在一個類文件中，注釋主要分為頭文件注釋、類注釋、變量注釋、方法注釋，下面對各種注釋方式進行詳細介紹。

一個可用的模版格式如下：

* File Name：${file_name}

* Version：V1.0

* Author：zhaokaiqiang

* Date：${date}

設置方法如下圖所示

Ø 類注釋。類注釋主要對類的功能，創建時間，作者進行說明。一個可用的模版如下

/**

* @ClassName: ${package_name}.${type_name}

* @Description:

* @author zhaokaiqiang

* @date ${date} ${time}

設置方法與頭文件注釋類似

Ø 方法注釋。方法注釋主要對一個方法的主要功能，返回值，異常信息進行描述。一個可用的模版如下

/**

* @Description: ${todo}

* @param

* @return ${return_type}

* @throws

Ø 字段注釋。變量注釋主要對變量的作用進行描述。可以使用單行注釋。

Ø 其他注釋。其他注釋包括復雜業務邏輯的注釋，for/while循環控制結構的注釋等其他任何通過注釋可以增加代碼可讀性的地方。

2.4開發規范

2.4.1控件命名規范

TextView ：tv_+描述

Button ：btn_+描述

ImageButton ：imgBtn_+描述

ImageView ：imgView_+描述

CheckBox ：chk_+描述

RadioButton ：rdoBtn_+描述

AnalogClock ：anaClk_+描述

DigitalClock ：DgtClk_+描述

DatePicker ：dtPk_+描述

TimePicker ：tmPk _+描述

ToggleButton ：tglBtn_+描述

EditText：et_+描述

ProgressBar：pb_+描述

SeekBar：skBar _+描述

AutoCompleteTextView：autoTv_+描述

MultiAutoCompleteTextView mlAutoTv_+描述

ZoomControls：zmCtrl_+描述

Include：ind_+描述

VideoView：vdoVi_+描述

WebView：webView_+描述

RatingBar：ratBar_+描述

Tab：tab_+描述

Spinner：spn_+描述

MapView: mapVi_+描述

ScrollView：sclVi_+描述

TextSwitcher：tvSwt_+描述

Gallery：gal_+描述

ImageSwitcher：imgSwt_+描述

GridView：gv_+描述

ListView：lv_+描述

控件說明如下：

• TextView - 文本顯示控件

• Button - 按鈕控件

• ImageButton - 圖片按鈕控件

• ImageView - 圖片顯示控件

• CheckBox - 復選框控件

• RadioButton - 單選框控件

• AnalogClock - 鐘表（帶表盤）控件

• DigitalClock - 電子表控件

• DatePicker - 日期選擇控件

• TimePicker - 時間選擇控件

• ToggleButton - 雙狀態按鈕控件

• EditText - 可編輯文本控件

• ProgressBar - 進度條控件

• SeekBar - 可拖動的進度條控件

• AutoCompleteTextView - 支持自動完成功能的可編輯文本控件

• MultiAutoCompleteTextView - 支持自動完成功能的可編輯文本控件，允許輸入多值（多值之間會自動地用指定的分隔符分開）

• ZoomControls - 放大/縮小按鈕控件

• Include - 整合控件

• VideoView - 視頻播放控件

• WebView - 浏覽器控件

• RatingBar - 評分控件

• Tab - 選項卡控件

• Spinner - 下拉框控件

• Chronometer - 計時器控件

• ScrollView - 滾動條控件

• TextSwitcher - 文字轉換器控件（改變文字時增加一些動畫效果）

• Gallery –畫廊控件

• ImageSwitcher - 圖片轉換器控件（改變圖片時增加一些動畫效果）

• GridView - 網格控件

• ListView - 列表控件

• ExpandableList - 支持展開/收縮功能的列表控件

2.4.2單位使用規范

控件長寬采用dp作為統一的衡量單位，字體使用sp作為統一衡量單位。

2.4.3切圖命名規范

具體命名規范，請看《Android切圖規范及命名規則》文檔。

2.4.4資源文件夾res下的規范

在res資源目錄下，應該至少包含下面的目錄結構

其中，各個版本的drawable中存放的內容如下

Ø drawable 存放使用xml文件實現的各種selector按下效果

Ø drawable-hdpi 存放480*800，480*854像素的圖片

Ø drawable-ldpi 存放240*320像素的圖片，現在基本廢棄

Ø drawable-mdpi 存放320*480像素的圖片，現在基本廢棄

Ø drawable-xhdpi 存放720*1280像素及以上的圖片

Ø drawable-xxhdpi 暫時只放144px的圖標

3.最佳實踐

本節描述在編碼中的最佳實踐，這些實踐並不強制使用，但它們是由技術人員使用多年並被證明行之有效的方法。當然，這些實踐的使用有些可能是不適用的，因此需要根據實際情況酌情使用。

3.1先寫注釋再寫代碼

寫代碼注釋的最好方法是在寫代碼之前就寫注釋。這使你在寫代碼之前可以想想代碼的功能和運行。而且這樣確保不會遺漏注釋。另一種方法是邊寫代碼邊寫注釋。因為注釋可以使代碼更易理解，所以在程序開發的過程中，也可以利用這一點。如果打算花些時間寫注釋，那麼至少你應從這個過程中獲得些什麼。

3.2在文檔中加入HEML標記

在文檔注釋中加入HTML標記，可使最後生成的技術文檔的格式豐富而變得更有表現力，因此強烈推薦采用在文檔注釋中加入HTML標記的做法。但是，由於Javadoc可在多種媒體中發布，可能會在一個不支持HTML的媒體上進行發布，因此在文檔注釋中加入HTML標記也會帶來一些潛在的問題，但在當前環境中不會出現問題。