Java命名規範與註釋規範
在面向物件程式設計中,對於類,物件,方法,變數等方面的命名是非常有技巧的。比如,大小寫的區分,使用不同字母開頭等等。但究其本,追其源,在為一個資源其名稱時
候,應該本著描述性以及唯一性這兩大特徵來命名,才能保證資源之間不衝突,並且每一個都便於記憶。
一、命名規範
(1)、包的命名:Java中包的名字全部是小寫字母。
包名按照域名的範圍從大到小逐步列出,恰好和Internet上的域名命名規則相反。由一組以".”連線的識別符號構成,通常第一個識別符號為符合網路域名的兩個或者三個英文小寫字
母。例如:net.frontfree.javagroup
轉:由於Java面向物件的特性,每名Java開發人員都可以編寫屬於自己的Java Package,為了保障每個Java Package命名的唯一性,在最新的Java程式設計規範中,要求開發人員在自
己定義的包名前加上唯
一的字首。由於網際網路上的域名稱是不會重複的,所以多數開發人員採用自己公司在網際網路上的域名稱作為自己程式包的唯一字首。例如: com.sun.swt.……。從而,我們知
道,一般公司命名為“com.公
司名.專案名.模組名....”。那,我們個人的專案又怎麼命名呢?
經過我對“個人的”單詞搜尋,有“individual、personal、private、one-man”,進一步對以上4個單詞詞意的分析,並在保證了唯一性,使用每個單詞的前4個字母作為字首,正好
和“com”也做了區分。如
下:
indi:個體專案,指個人發起,但非自己獨自完成的專案,可公開或私有專案,copyright主要屬於發起者。包名為“indi.發起者名.專案名.模組名.……”。
pers:個人專案,指個人發起,獨自完成,可分享的專案,copyright主要屬於個人。包名為“pers.個人名.專案名.模組名.……”。
priv:私有專案,指個人發起,獨自完成,非公開的私人使用的專案,copyright屬於個人。包名為“priv.個人名.專案名.模組名.……”。
onem :與“indi”相同,推薦使用“indi”。另外,我為了區分團隊專案和前面所說專案的區分,還有了一下擴充套件:
team :團隊專案,指由團隊發起,並由該團隊開發的專案,copyright屬於該團隊所有。包名為“team.團隊名.專案名.模組名.……”。
com :公司專案,copyright由專案發起的公司所有。包名為“com.公司名.專案名.模組名.……”。
(2)、類與介面的命名:類的名字必須由大寫字母開頭而單詞中的其他字母均為小寫;如果類名稱由多個單片語成,則每個單詞的首字母均應為大寫例如TestPage;如果類名稱中
包含單詞縮寫,則這個所寫詞的每個字母均應大寫,如:XMLExample,還有一點命名技巧就是由於類是設計用來代表物件的,所以在命名類時應儘量選擇名詞。
(3)、方法的命名:方法的名字的第一個單詞應以小寫字母作為開頭,後面的單詞則用大寫字母開頭。可以為動詞或動詞+名詞組合。
設定/獲取某個值的Method,應該遵循setV/getV規範,返回長度的Method,應該命名為length。
測試某個布林值的Method,應該命名為isV。
將物件轉換為某個特定型別的Mehod應該命名為toF:getDate(); length(); isReady(); toOracleFormat()。
(4)、引數的命名:引數的命名規範和方法的命名規範相同,而且為了避免閱讀程式時造成迷惑,請在儘量保證引數名稱為一個單詞的情況下使引數的命名儘可能明確。
(5)、常量的命名:常量的名字應該都使用大寫字母,並且指出該常量完整含義。如果一個常量名稱由多個單片語成,則應該用下劃線來分割這些單詞。 例如: MAX_VALUE
(6)、變數的命名:
1、普通變數命名應該採用首字母小寫,其他字母首字母大寫的方式。
2、final或static變數的名字應該都大寫,並且指出完整含義。如果一個常量名稱由多個單片語成,則應該用下劃線來分割這些單詞。如:NUM_DAYS_IN_WEEK MAX_VALU
3、如果需要對變數名進行縮寫時,一定要注意整個程式碼中縮寫規則的一致性。如:context=ctx message=msg
4、通過在結尾處放置一個量詞,就可建立更加統一的變數。
First(一組變數中的第一個);Last(一組變數中的最後一個); Next(一組變數中的下一個變數) ;Prev(一組變數中的上一個) ;Cur(一組變數中的當前變數);
5. 無論什麼時候,均提倡應用常量取代數字、固定字串。也就是說,程式中除0,1以外,儘量不應該出現其他數字。
6. 索引變數:i、j、k等只作為小型迴圈的迴圈索引變數。
7. 邏輯變數:避免用flag來命名狀態變數,用is來命名邏輯變數。如:if(isClosed){ dosomeworks; return; }
(7)、陣列的命名:
總是使用以下方式定義陣列:int[] arr = new int[10];
禁止使用C語言的是形式:禁止 int arr[] = new int[10];
(8)、集合的命名:陣列或者容器推薦命名方式為名詞+s的方式。
例如:List persons = getPerson(); for(Person person : persons){ dosomeworks; }
(9)、泛型的命名:應該儘量簡明扼要(最好是一個字母),以利於與普通的class或interface區分。
Container中的Element應該用E表示;Map裡的key用K表示,value用V;Type用T表示;異常用X表示。
如果需要接收多個Type型別的引數,應該用鄰接T的大寫字母。例如S來依次表示,當然也可以用T1, T2這樣的方式。
public class HashSet extends AbstractSet {…}
public class HashMap extends AbstractMap {…}
public class ThreadLocal {…}
public interface Functor { T val() throws X; }
二、推薦的命名
(1)、當要區別介面和實現類的時候,可以在類的後面加上“Impl”:<span style="white-space:pre"> </span>//用“Exception”做為類命名的結尾
<span style="white-space:pre"> </span>DataNotFoundException InvalidArgumentException
(2)、抽象類最好能用“Abstract”做為類命名的開頭:
<span style="white-space:pre"> </span>AbstractBeanDefinition AbstractBeanFactory
(3)、Test類最好能用“Test”做為類命名的結尾<span style="white-space:pre"> </span>ContainerTest
(4)、簡稱與縮寫(不推薦使用)
1、cp代表colorPoint;buf代表buffer;off代表offset;len代表length;
2、除非是在迴圈中,否則一般不推薦使用單個字母作為變數名,不過也有例外,即約定俗成的單個字母:
b代表byte;c代表char;d代表double;e代表Exception;f代表float;
i, j, k代表整數l代表long;o代表Object;s代表String;v代表某些型別的特定值
(5)、程式碼風格:
花括號:統一採用以下格式:
<span style="background-color: rgb(255, 255, 255);"><span style="color:#000099;"><span style="white-space: pre;"> </span>if(bool experssion){
<span style="white-space: pre;"> </span>dosomework;
<span style="white-space: pre;"> </span>}</span></span>
除非花括號中為空,不然任何情況下不能省略花括號,並且花括號必須換行,例如:if(i==0){ return; } while(true) {}
三、註釋規範 (1)、類註釋:在每個類前面必須加上類註釋,註釋模板如下:/**
* Copyright (C), 2006-2010, ChengDu Lovo info. Co., Ltd.
* FileName: Test.java
*
* 類的詳細說明
* @author 類建立者姓名
* @Date 建日期
* @version 1.00
*/
<span style="color:#ff0000;"><span style="font-size: 11.8518514633179px; font-family: Arial, Helvetica, sans-serif; background-color: rgb(255, 255, 255);">(2)、屬性註釋:</span><span style="font-size: 11.8518514633179px; font-family: Arial, Helvetica, sans-serif; background-color: rgb(255, 255, 255);">在每個屬性前面必須加上屬性註釋,註釋模板如下:</span></span>
/** 提示資訊 */
private String strMsg = null;
(3)、方法註釋:在每個方法前面必須加上方法註釋,註釋模板如下:
/**
* 類方法的詳細使用說明
*
* @param 引數1 引數1的使用說明
* @return 返回結果的說明
* @throws 異常型別.錯誤程式碼 註明從此類方法中丟擲異常的說明
*/
(4)、構造方法註釋:在每個構造方法前面必須加上註釋,註釋模板如下:
/**
* 構造方法的詳細使用說明
*
* @param 引數1 引數1的使用說明
* @throws 異常型別.錯誤程式碼 註明從此類方法中丟擲異常的說明
*/
(5)、方法內部註釋:在方法內部使用單行或者多行註釋,該註釋根據實際情況新增。如:
//背景顏色
Color bgColor = Color.RED