工作項目中的代碼規範

1、規範

1.1 命名規範

命名對於開發人員一直是個敏感的問題，好的命名能夠閱讀更加容易理解，節省閱讀的時間。總的命名原則是通俗易懂，讓閱讀者一眼就能看出該項命名具體的代表什麼意思。

1.1.1 包命名規範

一個唯一包名的前綴總是全部小寫的ASCII字母並且是一個頂級域名，通常是com，edu，gov，mil，net，org，或1981年ISO3166標準所指定的標識國家的英文雙字符代碼。包名的後續部分根據不同機構各自內部的命名規範而不盡相同。這類命名規範可能以特定目錄名的組成來區分部門(department)，項目(project)，機器(machine)，或註冊名(loginnames)。Uwen的所有android程序包的開頭都必須是com.uwen.melo.子項目名，如全城搗蛋項目,則開頭爲com.uwen.melo.themonkey，以下列舉在項目中常用的包命名，詳細見表1.1。

包名	功能	描述
com.uwen.melo.子項目名.activities	activity所在的包	在該包下面，具體到模塊則還需要增加模塊的命名空間，如用戶登錄模塊的activity對應的包名爲 com.uwen.melo.項目名.activities.user
com.uwen.melo.子項目名.adapter	適配器所在的包	項目中所有的適配器都放在該包下面，具體到模塊則還需要增加模塊的命名空間，如用戶登錄模塊的適配器對應的包名爲 com.uwen.melo.子項目名.adapter.user
com.uwen.melo.子項目名.cfg	配置文件所在的包	項目中與配置有關的java文件應該放在此包下
com.uwen.melo.子項目名.common	常量文件所在的包	項目中固定的參數相關的文件都應該放在此包下
com.uwen.melo.子項目名.http	網絡請求文件所在包	項目中跟網絡請求相關的包應該放在此包中
com.uwen.melo.子項目名.media	多媒體操作所在的包	項目中存在多媒體文件
com.uwen.melo.子項目名.model	實體類所在的包	項目中所有的實體類都放在該包下面，具體到模塊則還需要增加模塊的命名空間，如用戶登錄模塊的實體類對應的包名爲 com.uwen.melo.子項目名.model.user
com.uwen.melo.子項目名.util	工具類所在的包	所有的工具類均放在此包中，同時工具類的命名也需要以Util結尾，如校驗的工具類的名字爲，ValidateUtil.java，具體的參見類名的命名規範
com.uwen.melo.子項目名.widget	擴展組件所在的包	項目中所有擴展組件相關的文件都應該放在此包下
com.uwen.melo.子項目名.views	Activity中的真正的業務邏輯所在的包	在該包下，還需要劃分如下三個功能子包。分別爲 creates.impl:具體實現包名 exceptions:異常包名 interfaze:接口包名。 其中creates.impl包下還需要根據具體的模塊來進行命名空間的劃分，如用戶模塊則爲creates.impl.user。 interfaze用於存放業務邏輯中回調函數和相應的接口

表1.1主體包命名規範表

1.1.2 類命名規範

類名是個一名詞，採用大小寫混合的方式，每個單詞的首字母大寫。儘量使你的類名簡潔而富於描述。使用完整單詞，避免縮寫詞(除非該縮寫詞被更廣泛使用，像URL，HTML).

在uwen的android編碼規範中，類命名規範應該遵循功能名+功能類型名的命名規則，表1.2是優問android項目中常見的命名規範說明。

功能類	說明
Activtivity類	項目中所有的activity類文件的命名形式爲 ***Activity,其中***代表的是功能名，如登錄模塊的activity命名爲LoginActivity
適配器類(Adapter)	項目中所有的適配器類文件的命名形式爲 ***Adapter,其中***代表的是功能名，如用戶列表的適配器命名爲UserAdapter
常量類(Constant)	項目中所有的常量類文件的命名形式爲 ***Constant,其中***代表的是功能名，如常用常量的命名爲CommonConstant
配置類(Cfg)	項目中所有的配置類文件的命名形式爲 ***Cfg,其中***代表的是功能名，如服務器列表的配置類文件命名爲，ServerListCfg
工具類(Util)	項目中所有的工具類的命名形式爲 ***Util,其中***代表的是功能名，如驗證工具類命名爲，ValidateUtil
接口類(Interface)	項目中所有的接口的命名形式爲 I***,其中***代表的是功能名，如註冊接口的命名爲，IRegister
回調函數類(Callback)	項目中所有的回調函數的命名形式爲 ***Callback,其中***代表的是功能名，如註冊功能的回調函數的命名爲，RegisterCallback
實體類(Model)	項目中所有的實體類的命名形式爲 ***VO或者是***Bean,其中***代表的是功能名，如用戶信息實體類的命名爲，UserVO或UserBean
異常類(Exception	項目中所有的異常類的命名形式爲 ***Exception，如用戶信息異常的命名爲，UserInfoException
線程類(Thread)	項目中所有的線程類的命名形式爲 ***Thread，如下載線程的命名爲，DownloadThread
異步線程類(AsynTask)	項目中所有異步線程類的命名形式爲 ***AsynTask，如下載異步線程的命名爲，DownloadAsynTask

表1.2 優問android項目中常見的命名規範

1.1.3 方法命名規範

方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。如run()，runFast()，getBackground();

1.1.4變量命名規範

除了變量名外，所有實例，包括類，類常量，均採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。變量名不應以下劃線或美元符號開頭，儘管這在語法上是允許的。變量名應簡短且富於描述。變量名的選用應該易於記憶，即，能夠指出其用途。儘量避免單個字符的變量名，除非是一次性的臨時變量。臨時變量通常被取名爲i，j，k，m和n，它們一般用於整型；c，d，e，它們一般用於字符型。

1.1.5常量命名規範

類常量和ANSI常量的聲明，應該全部大寫，單詞間用下劃線隔開。(儘量避免ANSI常量，容易引起錯誤)

1.2 註釋規範

Java除了可以採用我們常見的註釋方式之外，Java語言規範還定義了一種特殊的註釋，即Javadoc註釋，它是用來記錄代碼中的API的。註釋以/**開頭，並以*/結束，註釋可以包含一些HTML標記符和專門的關鍵詞。
例如：

/**
*This isan exampleof
*Javadoc
*@authordarchon
*@version0.1,08/11/2014
*/

在每個程序的最開始部分，使用Javadoc註釋對程序的總體描述以及版權信息，之後在主程序中爲每個類、接口、方法、字段添加Javadoc註釋，每個註釋的開頭部分先用一句話概括該類、接口、方法、字段所完成的功能，這句話應單獨佔據一行以突出其概括作用，在這句話後面跟更加詳細的描述段落。在描述性段落之後還可以跟隨一些以Javadoc註釋標籤開頭的特殊段落，例如上面例中的@auther和@version，這些段落將在生成文檔中以特定方式顯示。