Google 出品的 Java 編碼規範,強烈推薦,既權威又科學
這份文檔是 Google Java 編程風格規範的完整定義。當且僅當一個Java源文件符合此文檔中的規則, 我們才認為它符合Google的Java編程風格。原文:google.github.io/styleguide/javaguide.html 譯者:Hawstein 來源:hawstein.com/2014/01/20/google-java-style/
與其它的編程風格指南一樣,這裡所討論的不僅僅是編碼格式美不美觀的問題, 同時也討論一些約定及編碼標準。然而,這份文檔主要側重於我們所普遍遵循的規則, 對於那些不是明確強制要求的,我們盡量避免提供意見。
在逆鋒起筆微信公眾號後台回復關鍵字:規範,可獲取高清 PDF 版的下載地址《Google Java編程風格指南/規範》
如果你想獲取阿里巴巴最新的《Java開發手冊》,請關注逆鋒起筆微信公眾號,在後台回復關鍵字:java手冊,既可獲取。
1.1 術語說明
在本文檔中,除非另有說明:
1、術語class可表示一個普通類,枚舉類,介面或是annotation類型( @interface)
2、術語comment只用來指代實現的注釋(implementation comments),我們不使用「documentation comments」一詞,而是用Javadoc。
其他的術語說明會偶爾在後面的文檔出現。
1.2 指南說明
本文檔中的示例程式碼並不作為規範。也就是說,雖然示例程式碼是遵循Google編程風格,但並不意味著這是展現這些程式碼的唯一方式。示例中的格式選擇不應該被強制定為規則。
源文件基礎
2.1 文件名
源文件以其最頂層的類名來命名,大小寫敏感,文件擴展名為 .java。
2.2 文件編碼:UTF-8
源文件編碼格式為UTF-8。
2.3 特殊字元
2.3.1 空白字元
除了行結束符序列,ASCII水平空格字元(0x20,即空格)是源文件中唯一允許出現的空白字元,這意味著:
1、所有其它字元串中的空白字元都要進行轉義。
2、製表符不用於縮進。
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字元,如果真的有需要的話)
源文件結構
一個源文件包含(按順序地):
1、許可證或版權資訊(如有需要)
2、package語句
3、import語句
4、一個頂級類(只有一個)
以上每個部分之間用一個空行隔開。
3.1 許可證或版權資訊
如果一個文件包含許可證或版權資訊,那麼它應當被放在文件最前面。
3.2 package語句
package語句不換行,列限制(4.4節)並不適用於package語句。(即package語句寫在一行里)
3.3 import語句
3.3.1 import不要使用通配符
即,不要出現類似這樣的import語句:importjava.util.*;
3.3.2 不要換行
import語句不換行,列限制(4.4節)並不適用於import語句。(每個import語句獨立成行)
3.3.3 順序和間距
import語句可分為以下幾組,按照這個順序,每組由一個空行分隔:
1、所有的靜態導入獨立成組
2、 com.google imports(僅當這個源文件是在 com.google包下)
3、第三方的包。每個頂級包為一組,字典序。例如:android, com, junit, org, sun
4、 java imports
5、 javax imports
組內不空行,按字典序排列。
公眾號
逆鋒起筆
專註分享Java
、Python
、前端、大廠經驗、職業發展乾貨;每天下午 14:40 推送,每個程式設計師值得關注的技術平台。關注即送小編整理的精品影片教程。
3.4 類聲明
3.4.1 只有一個頂級類聲明
每個頂級類都在一個與它同名的源文件中(當然,還包含 .java後綴)。
例外:package-info.java,該文件中可沒有 package-info類。
3.4.2 類成員順序
類的成員順序對易學性有很大的影響,但這也不存在唯一的通用法則。不同的類對成員的排序可能是不同的。最重要的一點,每個類應該以某種邏輯去排序它的成員,維護者應該要能解釋這種排序邏輯。
比如, 新的方法不能總是習慣性地添加到類的結尾,因為這樣就是按時間順序而非某種邏輯來排序的。
3.4.2.1 重載:永不分離
當一個類有多個構造函數,或是多個同名方法,這些函數/方法應該按順序出現在一起,中間不要放進其它函數/方法。
格式
術語說明:塊狀結構(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):
1、左大括弧前不換行
2、左大括弧後換行
3、右大括弧前換行
4、如果右大括弧是一個語句、函數體或類的終止,則右大括弧後換行; 否則不換行。例如,如果右大括弧後面是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 塊縮進:2個空格
每當開始一個新的塊,縮進增加2個空格,當塊結束時,縮進返回先前的縮進級別。縮進級別適用於程式碼和注釋。(見4.1.2節中的程式碼示例)
4.3 一行一個語句
每個語句後要換行。
4.4 列限制:80或100
一個項目可以選擇一行80個字元或100個字元的列限制,除了下述例外,任何一行如果超過這個字元數限制,必須自動換行。
例外:
1、不可能滿足列限制的行(例如,Javadoc中的一個長URL,或是一個長的JSNI方法參考)。
2、 package和 import語句(見3.2節和3.3節)。
3、注釋中那些可能被剪切並粘貼到shell中的命令行。
4.5 自動換行
術語說明:一般情況下,一行長程式碼為了避免超出列限制(80或100個字元)而被分為多行,我們稱之為自動換行(line-wrapping)。
我們並沒有全面,確定性的準則來決定在每一種情況下如何自動換行。很多時候,對於同一段程式碼會有好幾種有效的自動換行方式。
Tip: 提取方法或局部變數可以在不換行的情況下解決程式碼過長的問題(是合理縮短命名長度吧)
4.5.1 從哪裡斷開
自動換行的基本準則是:更傾向於在更高的語法級別處斷開。
1、如果在 非賦值運算符處斷開,那麼在該符號前斷開(比如+,它將位於下一行)。注意:這一點與Google其它語言的編程風格不同(如C++和JavaScript)。這條規則也適用於以下「類運算符」符號:點分隔符(.),類型界限中的&( <TextendsFoo&Bar>),catch塊中的管道符號( catch(FooException|BarExceptione)
2、如果在 賦值運算符處斷開,通常的做法是在該符號後斷開(比如=,它與前面的內容留在同一行)。這條規則也適用於 foreach語句中的分號。
3、方法名或構造函數名與左括弧留在同一行。
4、逗號(,)與其前面的內容留在同一行。
4.5.2 自動換行時縮進至少+4個空格
自動換行時,第一行後的每一行至少比第一行多縮進4個空格(注意:製表符不用於縮進。見2.3.1節)。
當存在連續自動換行時,縮進可能會多縮進不只4個空格(語法元素存在多級時)。一般而言,兩個連續行使用相同的縮進當且僅當它們開始於同級語法元素。
第4.6.3水平對齊一節中指出,不鼓勵使用可變數目的空格來對齊前面行的符號。
4.6 空白
4.6.1 垂直空白
以下情況需要使用一個空行:
1、類內連續的成員之間:欄位,構造函數,方法,嵌套類,靜態初始化塊,實例初始化塊。
例如:兩個連續欄位之間的空行是可選的,用於欄位的空行主要用來對欄位進行邏輯分組。
2、在函數體內,語句的邏輯分組間使用空行。
3、類內的第一個成員前或最後一個成員後的空行是可選的(既不鼓勵也不反對這樣做,視個人喜好而定)。
4、要滿足本文檔中其他節的空行要求(比如3.3節:import語句)
多個連續的空行是允許的,但沒有必要這樣做(我們也不鼓勵這樣做)。
4.6.2 水平空白
除了語言需求和其它規則,並且除了文字,注釋和Javadoc用到單個空格,單個ASCII空格也出現在以下幾個地方:
1、分隔任何保留字與緊隨其後的左括弧( ()(如 if,forcatch等)。
2、分隔任何保留字與其前面的右大括弧( })(如 else,catch)。
3、在任何左大括弧前( {),兩個例外:
@SomeAnnotation({a,b})(不使用空格)。String[][]x=foo;(大括弧間沒有空格,見下面的Note)。
4、在任何二元或三元運算符的兩側。這也適用於以下「類運算符」符號:
類型界限中的&( <TextendsFoo&Bar>)。catch塊中的管道符號( catch(FooException|BarExceptione)。foreach語句中的分號。
5、在 ,:;及右括弧( ))後
6、如果在一條語句後做注釋,則雙斜杠(//)兩邊都要空格。這裡可以允許多個空格,但沒有必要。
7、類型和變數之間:List
8、數組初始化中,大括弧內的空格是可選的,即 newint[]{5,6}和 newint[]{5,6}都是可以的。
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運算符優先順序表。
公眾號
逆鋒起筆
專註分享Java
、Python
、前端、大廠經驗、職業發展乾貨;每天下午 14:40 推送,每個程式設計師值得關注的技術平台。關注即送小編整理的精品影片教程。
4.8 具體結構
4.8.1 枚舉類
枚舉常量間用逗號隔開,換行可選。
沒有方法和文檔的枚舉類可寫成數組初始化的格式:
private enum Suit
{ CLUBS, HEARTS, SPADES, DIAMONDS }
由於枚舉類也是一個類,因此所有適用於其它類的格式規則也適用於枚舉類。
4.8.2 變數聲明
4.8.2.1 每次只聲明一個變數
不要使用組合聲明,比如 inta,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, 而非 Stringargs[]。
4.8.4 switch語句
術語說明:switch塊的大括弧內是一個或多個語句組。每個語句組包含一個或多個switch標籤( caseFOO:或 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節,自動換行),因此縮進級別不變。例如:
@Override
@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.1 對所有標識符都通用的規則
標識符只能使用ASCII字母和數字,因此每個有效的標識符名稱都能匹配正則表達式 \w+。
在Google其它程式語言風格中使用的特殊前綴或後綴,如 name_, mName, s_name和 kName,在Java編程風格中都不再使用。
5.2 標識符類型的規則
5.2.1 包名
包名全部小寫,連續的單詞只是簡單地連接起來,不使用下劃線。
5.2.2 類名
類名都以 UpperCamelCase風格編寫。
類名通常是名詞或名詞短語,介面名稱有時可能是形容詞或形容詞短語。現在還沒有特定的規則或行之有效的約定來命名註解類型。
測試類的命名以它要測試的類的名稱開始,以 Test結束。例如, HashTest或 HashIntegrationTest。
5.2.3 方法名
方法名都以 lowerCamelCase風格編寫。
方法名通常是動詞或動詞短語。
下劃線可能出現在JUnit測試方法名稱中用以分隔名稱的邏輯組件。一個典型的模式是:test
5.2.4 常量名
常量名命名模式為 CONSTANT_CASE,全部字母大寫,用下劃線分隔單詞。那,到底什麼算是一個常量?
每個常量都是一個靜態final欄位,但不是所有靜態final欄位都是常量。在決定一個欄位是否是一個常量時, 考慮它是否真的感覺像是一個常量。例如,如果任何一個該實例的觀測狀態是可變的,則它幾乎肯定不會是一個常量。只是永遠不 打算改變對象一般是不夠的,它要真的一直不變才能將它示為常量。
這些名字通常是名詞或名詞短語。
5.2.5 非常量欄位名
非常量欄位名以 lowerCamelCase風格編寫。
這些名字通常是名詞或名詞短語。
5.2.6 參數名
參數名以 lowerCamelCase風格編寫。
參數應該避免用單個字元命名。
5.2.7 局部變數名
局部變數名以 lowerCamelCase風格編寫,比起其它類型的名稱,局部變數名可以有更為寬鬆的縮寫。
雖然縮寫更寬鬆,但還是要避免用單字元進行命名,除了臨時變數和循環變數。
即使局部變數是final和不可改變的,也不應該把它示為常量,自然也不能用常量的規則去命名它。
5.2.8 類型變數名
類型變數可用以下兩種風格之一進行命名:
1、單個的大寫字母,後面可以跟一個數字(如:E, T, X, T2)。
2、以類命名方式(5.2.2節),後面加個大寫的T(如:RequestT, FooBarT)。
5.3 駝峰式命名法(CamelCase)
駝峰式命名法分大駝峰式命名法( UpperCamelCase)和小駝峰式命名法( lowerCamelCase)。有時,我們有不只一種合理的方式將一個英語片語轉換成駝峰形式,如縮略語或不尋常的結構(例如」IPv6」或」iOS」)。Google指定了以下的轉換方案。推薦:告別狗屎程式碼,請記住這 11 條編碼秘訣!
名字從 散文形式(prose form)開始:
1、把短語轉換為純ASCII碼,並且移除任何單引號。例如:」Müller』s algorithm」將變成」Muellers algorithm」。
2、把這個結果切分成單詞,在空格或其它標點符號(通常是連字元)處分割開。
推薦:如果某個單詞已經有了常用的駝峰表示形式,按它的組成將它分割開(如」AdWords」將分割成」ad words」)。需要注意的是」iOS」並不是一個真正的駝峰表示形式,因此該推薦對它並不適用。
3、現在將所有字母都小寫(包括縮寫),然後將單詞的第一個字母大寫:每個單詞的第一個字母都大寫,來得到大駝峰式命名。除了第一個單詞,每個單詞的第一個字母都大寫,來得到小駝峰式命名。
4、最後將所有的單詞連接起來得到一個標識符。
示例:
加星號處表示可以,但不推薦。
Note:在英語中,某些帶有連字元的單詞形式不唯一。例如:」nonempty」和」non-empty」都是正確的,因此方法名 checkNonempty和 checkNonEmpty也都是正確的。
公眾號
逆鋒起筆
專註分享Java
、Python
、前端、大廠經驗、職業發展乾貨;每天下午 14:40 推送,每個程式設計師值得關注的技術平台。關注即送小編整理的精品影片教程。
編程實踐
6.1 @Override:能用則用
只要是合法的,就把 @Override註解給用上。
6.2 捕獲的異常:不能忽視
除了下面的例子,對捕獲的異常不做響應是極少正確的。(典型的響應方式是列印日誌,或者如果它被認為是不可能的,則把它當作一個 AssertionError重新拋出。)
如果它確實是不需要在catch塊中做任何響應,需要做注釋加以說明(如下面的例子)。
例外:在測試中,如果一個捕獲的異常被命名為 expected,則它可以被不加註釋地忽略。下面是一種非常常見的情形,用以確保所測試的方法會拋出一個期望中的異常, 因此在這裡就沒有必要加註釋。
6.3 靜態成員:使用類進行調用
使用類名調用靜態的類成員,而不是具體某個對象或表達式。
6.4 Finalizers: 禁用
極少會去重寫 Object.finalize。
Tip:不要使用finalize。如果你非要使用它,請先仔細閱讀和理解Effective Java 第7條款:「Avoid Finalizers」,然後不要使用它。
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)之前(如果有的話)。除了第一個段落,每個段落第一個單詞前都有標籤
,並且它和第一個單詞間沒有空格。
7.1.3 Javadoc標記
標準的Javadoc標記按以下順序出現:@param, @return, @throws, @deprecated, 前面這4種標記如果出現,描述都不能為空。當描述無法在一行中容納,連續行需要至少再縮進4個空格。
7.2 摘要片段
每個類或成員的Javadoc以一個簡短的摘要片段開始。這個片段是非常重要的,在某些情況下,它是唯一出現的文本,比如在類和方法索引中。
這只是一個小片段,可以是一個名詞短語或動詞短語,但不是一個完整的句子。它不會以 A{@codeFoo}isa…或 Thismethod returns…開頭, 它也不會是一個完整的祈使句,如 Savethe 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,這樣更統一更友好。
在逆鋒起筆微信公眾號後台回復關鍵字:規範,可獲取高清 PDF 版的下載地址《Google Java編程風格指南/規範》
如果你想獲取阿里巴巴最新的《Java開發手冊》,請關注逆鋒起筆微信公眾號,在後台回復關鍵字:java手冊,既可獲取。
公眾號
逆鋒起筆
專註分享Java
、Python
、前端、大廠經驗、職業發展乾貨;每天下午 14:40 推送,每個程式設計師值得關注的技術平台。關注即送小編整理的精品影片教程。