Google Java Style Guide

這份文檔是Google Java編程風(fēng)格規(guī)范的完整定義抗悍。當(dāng)且僅當(dāng)一個Java源文件符合此文檔中的規(guī)則，我們才認(rèn)為它符合Google的Java編程風(fēng)格即横。

與其它的編程風(fēng)格指南一樣是目，這里所討論的不僅僅是編碼格式美不美觀的問題闷畸，同時也討論一些約定及編碼標(biāo)準(zhǔn)殃恒。然而，這份文檔主要側(cè)重于我們所普遍遵循的規(guī)則迂猴，對于那些不是明確強(qiáng)制要求的慕淡，我們盡量避免提供意見。

1.1 術(shù)語說明

在本文檔中沸毁，除非另有說明：

術(shù)語class可表示一個普通類峰髓，枚舉類，接口或是annotation類型(@interface)
術(shù)語comment只用來指代實(shí)現(xiàn)的注釋(implementation comments)息尺，我們不使用“documentation comments”一詞携兵，而是用Javadoc。

其他的術(shù)語說明會偶爾在后面的文檔出現(xiàn)搂誉。

1.2 指南說明

本文檔中的示例代碼并不作為規(guī)范徐紧。也就是說，雖然示例代碼是遵循Google編程風(fēng)格炭懊，但并不意味著這是展現(xiàn)這些代碼的唯一方式并级。示例中的格式選擇不應(yīng)該被強(qiáng)制定為規(guī)則。

源文件基礎(chǔ)

2.1 文件名

源文件以其最頂層的類名來命名侮腹，大小寫敏感嘲碧，文件擴(kuò)展名為.java。

2.2 文件編碼：UTF-8

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

2.3 特殊字符

2.3.1 空白字符

除了行結(jié)束符序列愈涩，ASCII水平空格字符(0×20，即空格)是源文件中唯一允許出現(xiàn)的空白字符至非，這意味著：

所有其它字符串中的空白字符都要進(jìn)行轉(zhuǎn)義钠署。
制表符不用于縮進(jìn)。

2.3.2 特殊轉(zhuǎn)義序列

對于具有特殊轉(zhuǎn)義序列的任何字符(\b, \t, \n, \f, \r, “, ‘及)荒椭，我們使用它的轉(zhuǎn)義序列谐鼎，而不是相應(yīng)的八進(jìn)制(比如\012)或Unicode(比如\u000a)轉(zhuǎn)義。

2.3.3 非ASCII字符

對于剩余的非ASCII字符趣惠，是使用實(shí)際的Unicode字符(比如∞)狸棍，還是使用等價的Unicode轉(zhuǎn)義符(比如\u221e)，取決于哪個能讓代碼更易于閱讀和理解味悄。

Tip: 在使用Unicode轉(zhuǎn)義符或是一些實(shí)際的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茧球，對于非打印字符，使用轉(zhuǎn)義星持，并在必要時寫上注釋

提示: 永遠(yuǎn)不要因?yàn)閾?dān)心某些程序可能無法正確處理非 ascii 字符而降低代碼的可讀性抢埋。如果出現(xiàn)這種情況，那些程序就會被破壞督暂，必須修復(fù)揪垄。

3 源文件結(jié)構(gòu)

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

許可證或版權(quán)信息(如有需要)
package語句
import語句
一個頂級類(只有一個)

以上每個部分之間用一個空行隔開。

3.1 許可證或版權(quán)信息

如果一個文件包含許可證或版權(quán)信息逻翁，那么它應(yīng)當(dāng)被放在文件最前面饥努。

3.2 package語句

package語句不換行，列限制(4.4節(jié))并不適用于package語句八回。(即package語句寫在一行里)

3.3 import語句

3.3.1 import不要使用通配符

不使用通配符導(dǎo)入import java.util.*;肪凛，無論是靜態(tài)導(dǎo)入還是其他導(dǎo)入。

3.3.2 不要換行

import語句不換行辽社，列限制(4.4節(jié), 列限制: 100)并不適用于import語句伟墙。(每個import語句獨(dú)立成行)

3.3.3 順序和間距

import語句可分為以下幾組，按照這個順序滴铅，每組由一個空行分隔：

單個塊中的所有靜態(tài)導(dǎo)入
單個塊中的所有非靜態(tài)導(dǎo)入

如果同時存在靜態(tài)和非靜態(tài)導(dǎo)入戳葵，則用一個空行分隔這兩個塊。導(dǎo)入語句之間沒有其他空行汉匙。

3.3.4 不要使用類的靜態(tài)導(dǎo)入

靜態(tài)導(dǎo)入不要用于靜態(tài)嵌套類拱烁，它們是通過正常導(dǎo)入導(dǎo)入的。

3.4 類聲明

3.4.1 只有一個頂級類聲明

每個頂級類都在一個與它同名的源文件中噩翠。

例外：package-info.java戏自，該文件中可沒有package-info類。

3.4.2 類成員順序

類的成員順序?qū)σ讓W(xué)性有很大的影響伤锚，但這也不存在唯一的通用法則擅笔。不同的類對成員的排序可能是不同的。最重要的一點(diǎn)屯援，每個類應(yīng)該以某種邏輯去排序它的成員猛们，維護(hù)者應(yīng)該要能解釋這種排序邏輯。比如狞洋，新的方法不能總是習(xí)慣性地添加到類的結(jié)尾弯淘，因?yàn)檫@樣就是按時間順序, 而非某種邏輯來排序的。

3.4.2.1 重載：永遠(yuǎn)不要拆分

當(dāng)一個類有多個構(gòu)造函數(shù)吉懊，或是多個同名方法庐橙，這些函數(shù)/方法應(yīng)該按順序出現(xiàn)在一起假勿，中間不要放進(jìn)其它函數(shù)/方法。

4 格式化

術(shù)語說明：塊狀結(jié)構(gòu)(block-like construct)指的是一個類态鳖，方法或構(gòu)造函數(shù)的主體废登。需要注意的是，數(shù)組初始化中的初始值可被選擇性地視為塊狀結(jié)構(gòu)(4.8.3.1節(jié))郁惜。

4.1 大括號

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

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

4.1.2 非空塊：K & R 風(fēng)格

對于非空塊和塊狀結(jié)構(gòu)，大括號遵循 Kernighan 和 Ritchie 風(fēng)格 (Egyptian brackets):

左大括號前不換行
左大括號后換行
右大括號前換行
如果右大括號是一個語句缤沦、函數(shù)體或類的終止虎韵，則右大括號后換行; 否則不換行。例如缸废，如果右大括號后面是else或逗號包蓝，則不換行。

示例：

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
    @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    } else if (otherCondition()) {
      somethingElse();
    } else {
      lastThing();
    }
  }
};

4.8.1節(jié)給出了enum類的一些例外企量。

4.1.3 空塊：可以用簡潔版本

一個空的塊狀結(jié)構(gòu)里什么也不包含测萎，大括號可以簡潔地寫成{}，不需要換行届巩。例外：如果它是一個多塊語句的一部分(if/else 或 try/catch/finally) 硅瞧，即使大括號內(nèi)沒內(nèi)容，右大括號也要換行恕汇。

示例：

  // This is acceptable
  void doNothing() {}

  // This is equally acceptable
  void doNothingElse() {
  }

這是不可接受的: 多塊語句中沒有簡潔的空塊

  // This is not acceptable: No concise empty blocks in a multi-block statement
  try {
    doSomething();
  } catch (Exception e) {}

4.2 塊縮進(jìn)：2個空格

每當(dāng)開始一個新的塊腕唧，縮進(jìn)增加2個空格，當(dāng)塊結(jié)束時瘾英，縮進(jìn)返回先前的縮進(jìn)級別枣接。縮進(jìn)級別適用于代碼和注釋缺谴。(見4.1.2節(jié)中的代碼示例)

4.3 一行一個語句

每個語句后跟一個換行符(a line break)但惶。

4.4 列限制(Column limit)：100

Java 代碼的列限制為100個字符，除了下述例外湿蛔，任何一行如果超過這個字符數(shù)限制榆骚，必須自動換行。

例外：

不可能滿足列限制的行(例如煌集，Javadoc中的一個長URL妓肢，或是一個長的JSNI方法參考)。
package和import語句(見3.2節(jié)和3.3節(jié))苫纤。
注釋中那些可能被剪切并粘貼到shell中的命令行碉钠。

4.5 自動換行(Line-wrapping)

術(shù)語注意: 當(dāng)本來可以合法占用一行的代碼被分成多行時纲缓，我們稱之為自動換行(line-wrapping)。

我們并沒有全面喊废，確定性的準(zhǔn)則來決定在每一種情況下如何自動換行祝高。很多時候，對于同一段代碼會有好幾種有效的自動換行方式污筷。

注意(Note): 雖然行換行的典型原因是為了避免溢出列限制工闺，但即使是實(shí)際上符合列限制的代碼也可能由作者自行決定是否進(jìn)行行換行。

提示(Tip): 提取方法或局部變量可以解決問題瓣蛀，而不需要換行陆蟆。

4.5.1 從哪里斷開

自動換行的基本準(zhǔn)則是：更傾向于在更高的語法級別處斷開。

如果在非賦值運(yùn)算符處斷開惋增，那么在該符號前斷開(比如+叠殷，它將位于下一行)。注意：這一點(diǎn)與Google其它語言的編程風(fēng)格不同(如C++和JavaScript)诈皿。這條規(guī)則也適用于以下“類運(yùn)算符”符號：點(diǎn)分隔符(.)林束，類型界限中的&（<T extends Foo & Bar>)，catch塊中的管道符號(catch (FooException | BarException e)
如果在賦值運(yùn)算符處斷開稽亏，通常的做法是在該符號后斷開(比如=壶冒，它與前面的內(nèi)容留在同一行)。這條規(guī)則也適用于foreach語句中的分號截歉。
方法名或構(gòu)造函數(shù)名與左括號留在同一行依痊。
逗號(,)與其前面的內(nèi)容留在同一行。
在 lambda 中怎披，與箭頭相鄰的直線不會斷開胸嘁，除非如果 lambda 的主體由單個無支撐表達(dá)式組成，那么在箭頭之后可能會立即出現(xiàn)斷開凉逛。例子:

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

注意: 換行主要目標(biāo)是有清晰的代碼性宏，而不一定是適合最小行數(shù)的代碼。

4.5.2 自動換行時縮進(jìn)至少+4個空格

自動換行時状飞，第一行后的每一行至少比第一行多縮進(jìn)4個空格(注意：制表符不用于縮進(jìn)毫胜。見2.3.1節(jié))。

當(dāng)存在連續(xù)自動換行時诬辈，縮進(jìn)可能會多縮進(jìn)不只4個空格(語法元素存在多級時)酵使。一般而言，兩個連續(xù)行使用相同的縮進(jìn)當(dāng)且僅當(dāng)它們開始于同級語法元素焙糟。

第4.6.3水平對齊一節(jié)中指出口渔，不鼓勵使用可變數(shù)目的空格來對齊前面行的符號。

4.6 空白

4.6.1 垂直空白

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

類內(nèi)連續(xù)的成員之間：字段穿撮，構(gòu)造函數(shù)缺脉，方法痪欲，嵌套類，靜態(tài)初始化塊攻礼，實(shí)例初始化塊业踢。
- 例外：兩個連續(xù)字段之間的空行是可選的，用于字段的空行主要用來對字段進(jìn)行邏輯分組礁扮。
在函數(shù)體內(nèi)知举，語句的邏輯分組間使用空行。
類內(nèi)的第一個成員前或最后一個成員后的空行是可選的(既不鼓勵也不反對這樣做太伊，視個人喜好而定)雇锡。
要滿足本文檔中其他節(jié)的空行要求(比如3.3節(jié)：import語句)

多個連續(xù)的空行是允許的，但沒有必要這樣做(我們也不鼓勵這樣做)倦畅。

4.6.2 水平空白

除了語言需求和其它規(guī)則，并且除了文字绣的，注釋和Javadoc用到單個空格叠赐，單個ASCII空格也出現(xiàn)在以下幾個地方：

分隔任何保留字與緊隨其后的左括號(()(如if, for catch等)。
分隔任何保留字與其前面的右大括號(})(如else, catch)屡江。
在任何左大括號前({)芭概，兩個例外：
- @SomeAnnotation({a, b})(不使用空格)。
- String[][] x = foo;(大括號間沒有空格惩嘉，見下面的Note)罢洲。
在任何二元或三元運(yùn)算符的兩側(cè)。這也適用于以下“類運(yùn)算符”符號：
- 類型界限中的&(<T extends Foo & Bar>)文黎。
- catch塊中的管道符號(catch (FooException | BarException e)惹苗。
- foreach語句中的分號。
在, : ;及右括號())后
如果在一條語句后做注釋耸峭，則雙斜杠(//)兩邊都要空格桩蓉。這里可以允許多個空格，但沒有必要劳闹。
類型和變量之間：List<String> list
數(shù)組初始化中院究，大括號內(nèi)的空格是可選的，即new int[] {5, 6}和new int[] { 5, 6 }都是可以的本涕。

Note：這個規(guī)則并不要求或禁止一行的開關(guān)或結(jié)尾需要額外的空格业汰，只對內(nèi)部空格做要求。

4.6.3 水平對齊：不做要求

術(shù)語說明：水平對齊指的是通過增加可變數(shù)量的空格來使某一行的字符與上一行的相應(yīng)字符對齊菩颖。

這是允許的(而且在不少地方可以看到這樣的代碼)样漆，但Google編程風(fēng)格對此不做要求。即使對于已經(jīng)使用水平對齊的代碼晦闰，我們也不需要去保持這種風(fēng)格氛濒。

以下示例先展示未對齊的代碼产场，然后是對齊的代碼：

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：對齊可增加代碼可讀性，但它為日后的維護(hù)帶來問題舞竿【┚埃考慮未來某個時候，我們需要修改一堆對齊的代碼中的一行骗奖。這可能導(dǎo)致原本很漂亮的對齊代碼變得錯位确徙。很可能它會提示你調(diào)整周圍代碼的空白來使這一堆代碼重新水平對齊(比如程序員想保持這種水平對齊的風(fēng)格)，這就會讓你做許多的無用功执桌，增加了reviewer的工作并且可能導(dǎo)致更多的合并沖突鄙皇。

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

除非作者和reviewer都認(rèn)為去掉小括號也不會使代碼被誤解，或是去掉小括號能讓代碼更易于閱讀仰挣，否則我們不應(yīng)該去掉小括號伴逸。我們沒有理由假設(shè)讀者能記住整個Java運(yùn)算符優(yōu)先級表。

4.8 特殊結(jié)構(gòu)

4.8.1 枚舉類

枚舉常量間用逗號隔開膘壶，換行可選错蝴。

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

沒有方法和文檔的枚舉類可寫成數(shù)組初始化的格式：

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

由于枚舉類也是一個類，因此所有適用于其它類的格式規(guī)則也適用于枚舉類颓芭。

4.8.2 變量聲明

4.8.2.1 每次只聲明一個變量

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

4.8.2.2 需要時才聲明亡问，并盡快進(jìn)行初始化

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

4.8.3 數(shù)組

4.8.3.1 數(shù)組初始化：可寫成塊狀結(jié)構(gòu)

數(shù)組初始化可以寫成塊狀結(jié)構(gòu)，比如床玻，下面的寫法都是OK的：

new int[] {           new int[] {
  0, 1, 2, 3            0,
}                       1,
                        2,
new int[] {             3,
  0, 1,               }
  2, 3
}                     new int[]
                          {0, 1, 2, 3}

4.8.3.2 非C風(fēng)格的數(shù)組聲明

中括號是類型的一部分：String[] args良狈，而非String args[]。

4.8.4 switch語句

術(shù)語說明：switch塊的大括號內(nèi)是一個或多個語句組笨枯。每個語句組包含一個或多個switch標(biāo)簽(case FOO:或default:)薪丁，后面跟著一條或多條語句。

4.8.4.1 縮進(jìn)

與其它塊狀結(jié)構(gòu)一致馅精，switch塊中的內(nèi)容縮進(jìn)為2個空格严嗜。

每個switch標(biāo)簽后新起一行，再縮進(jìn)2個空格洲敢，寫下一條或多條語句漫玄。

4.8.4.2 Fall-through：注釋

在一個switch塊內(nèi)，每個語句組要么通過break, continue, return或拋出異常來終止，要么通過一條注釋來說明程序?qū)⒗^續(xù)執(zhí)行到下一個語句組睦优，任何能表達(dá)這個意思的注釋都是OK的(典型的是用// fall through)渗常。這個特殊的注釋并不需要在最后一個語句組(一般是default)中出現(xiàn)。示例：

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)

注解緊跟在文檔塊后面，應(yīng)用于類隐孽、方法和構(gòu)造函數(shù)癌椿，一個注解獨(dú)占一行。這些換行不屬于自動換行(第4.5節(jié)菱阵，自動換行)踢俄，因此縮進(jìn)級別不變。例如：

@Override
@Nullable
public String getNameIfPresent() { ... }

例外：單個的注解可以和簽名的第一行出現(xiàn)在同一行晴及。例如：

@Override public int hashCode() { ... }

應(yīng)用于字段的注解緊隨文檔塊出現(xiàn)都办，應(yīng)用于字段的多個注解允許與字段出現(xiàn)在同一行。例如：

@Partial @Mock DataLoader loader;

參數(shù)和局部變量注解沒有特定規(guī)則虑稼。

4.8.6 注釋

4.8.6.1 塊注釋風(fēng)格

塊注釋與其周圍的代碼在同一縮進(jìn)級別琳钉。它們可以是/* ... */風(fēng)格，也可以是// ...風(fēng)格动雹。對于多行的/* ... */注釋槽卫，后續(xù)行必須從*開始跟压，并且與前一行的*對齊胰蝠。以下示例注釋都是OK的。

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

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

Tip：在寫多行注釋時茸塞，如果你希望在必要時能重新?lián)Q行(即注釋像段落風(fēng)格一樣)，那么使用/* ... */查剖。

4.8.7 修飾符

類和成員的modifiers如果存在钾虐，則按Java語言規(guī)范中推薦的順序出現(xiàn)。

Class and member modifiers, when present, appear in the order recommended by the Java Language Specification:

public protected private abstract default static final transient volatile synchronized native strictfp

5 命名約定

5.1 對所有標(biāo)識符都通用的規(guī)則

標(biāo)識符只能使用ASCII字母和數(shù)字笋庄，因此每個有效的標(biāo)識符名稱都能匹配正則表達(dá)式\w+效扫。

在Google其它編程語言風(fēng)格中使用的特殊前綴或后綴，如name_, mName, s_name和kName直砂，在Java編程風(fēng)格中都不再使用菌仁。

5.2 標(biāo)識符類型的規(guī)則

5.2.1 包名

包名全部小寫，連續(xù)的單詞只是簡單地連接起來静暂，不使用下劃線济丘。

5.2.2 類名

類名都以UpperCamelCase風(fēng)格編寫。

類名通常是名詞或名詞短語，接口名稱有時可能是形容詞或形容詞短語∧∶裕現(xiàn)在還沒有特定的規(guī)則或行之有效的約定來命名注解類型疟赊。

測試類的命名以它要測試的類的名稱開始，以Test結(jié)束峡碉。例如近哟，HashTest或HashIntegrationTest。

5.2.3 方法名

方法名都以lowerCamelCase風(fēng)格編寫异赫。

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

下劃線可能出現(xiàn)在JUnit測試方法名稱中用以分隔名稱的邏輯組件。一個典型的模式是：test<MethodUnderTest>_<state>塔拳，例如testPop_emptyStack鼠证。并不存在唯一正確的方式來命名測試方法。

5.2.4 常量名

常量名命名模式為CONSTANT_CASE靠抑，全部字母大寫，用下劃線分隔單詞颂碧。那，到底什么算是一個常量肌似？

每個常量都是一個靜態(tài)final字段，但不是所有靜態(tài)final字段都是常量诉瓦。在決定一個字段是否是一個常量時，考慮它是否真的感覺像是一個常量睬澡。例如，如果任何一個該實(shí)例的觀測狀態(tài)是可變的煞聪，則它幾乎肯定不會是一個常量斗躏。只是永遠(yuǎn)不打算改變對象一般是不夠的，它要真的一直不變才能將它示為常量啄糙。

// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
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 Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

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

5.2.5 非常量字段名

非常量字段名以lowerCamelCase風(fēng)格編寫碱鳞。

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

5.2.6 參數(shù)名

參數(shù)名以lowerCamelCase風(fēng)格編寫贵白。

參數(shù)應(yīng)該避免用單個字符命名。

5.2.7 局部變量名

局部變量名以lowerCamelCase風(fēng)格編寫猬膨，比起其它類型的名稱呛伴，局部變量名可以有更為寬松的縮寫热康。

雖然縮寫更寬松，但還是要避免用單字符進(jìn)行命名铁材，除了臨時變量和循環(huán)變量奕锌。

即使局部變量是final和不可改變的惊暴，也不應(yīng)該把它示為常量，自然也不能用常量的規(guī)則去命名它肄鸽。

5.2.8 類型變量名

類型變量可用以下兩種風(fēng)格之一進(jìn)行命名：

單個的大寫字母屡穗，后面可以跟一個數(shù)字(如：E, T, X, T2)村砂。
以類命名方式(5.2.2節(jié))屹逛，后面加個大寫的T(如：RequestT, FooBarT)。

5.3 駝峰式命名法(CamelCase)

駝峰式命名法分大駝峰式命名法(UpperCamelCase)和小駝峰式命名法(lowerCamelCase)评腺。有時蒿讥，我們有不只一種合理的方式將一個英語詞組轉(zhuǎn)換成駝峰形式，如縮略語或不尋常的結(jié)構(gòu)(例如”IPv6”或”iOS”)媒殉。Google指定了以下的轉(zhuǎn)換方案摔敛。

名字從散文形式(prose form)開始:

把短語轉(zhuǎn)換為純ASCII碼马昙，并且移除任何單引號。例如：”Müller’s algorithm”將變成”Muellers algorithm”攒暇。
把這個結(jié)果切分成單詞子房，在空格或其它標(biāo)點(diǎn)符號(通常是連字符)處分割開池颈。
- 推薦：如果某個單詞已經(jīng)有了常用的駝峰表示形式，按它的組成將它分割開(如”AdWords”將分割成”ad words”)每币。需要注意的是”iOS”并不是一個真正的駝峰表示形式琢歇，因此該推薦對它并不適用李茫。
現(xiàn)在將所有字母都小寫(包括縮寫)，然后將單詞的第一個字母大寫：
- 每個單詞的第一個字母都大寫秸侣，來得到大駝峰式命名宠互。
- 除了第一個單詞予跌，每個單詞的第一個字母都大寫，來得到小駝峰式命名频轿。
最后將所有的單詞連接起來得到一個標(biāo)識符。

示例：

Prose form           Correct            Incorrect
"XML HTTP request"  XmlHttpRequest  XMLHTTPRequest
"new customer ID"   newCustomerId   newCustomerID
"inner stopwatch"   innerStopwatch  innerStopWatch
"supports IPv6 on iOS?" supportsIpv6OnIos   supportsIPv6OnIOS
"YouTube importer"  YouTubeImporter
YoutubeImporter*

加星號處表示可以集币，但不推薦鞠苟。

Note：在英語中秽之，某些帶有連字符的單詞形式不唯一考榨。例如：”nonempty”和”non-empty”都是正確的，因此方法名checkNonempty和checkNonEmpty也都是正確的冀惭。

編程實(shí)踐

6.1 @Override：能用則用

只要是合法的散休，就把@Override注解給用上乐尊。

6.2 捕獲的異常：不能忽視

除了下面的例子，對捕獲的異常不做響應(yīng)是極少正確的限府。(典型的響應(yīng)方式是打印日志胁勺，或者如果它被認(rèn)為是不可能的独旷，則把它當(dāng)作一個AssertionError重新拋出势告。)

如果它確實(shí)是不需要在catch塊中做任何響應(yīng)抚恒，需要做注釋加以說明(如下面的例子)俭驮。

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} 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 靜態(tài)成員：使用類進(jìn)行調(diào)用

使用類名調(diào)用靜態(tài)的類成員售躁，而不是具體某個對象或表達(dá)式茴晋。

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4 Finalizers: 禁用

極少會去重寫Object.finalize诺擅。

Tip：不要使用finalize。如果你非要使用它凌盯，請先仔細(xì)閱讀和理解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的。當(dāng)整個Javadoc塊能容納于一行時(且沒有Javadoc標(biāo)記@XXX)症杏，可以使用單行形式厉颤。

7.1.2 段落

空行(即凡简，只包含最左側(cè)星號的行)會出現(xiàn)在段落之間和Javadoc標(biāo)記(@XXX)之前(如果有的話)。除了第一個段落帜乞，每個段落第一個單詞前都有標(biāo)簽<p>黎烈，并且它和第一個單詞間沒有空格。

7.1.3 Javadoc標(biāo)記

標(biāo)準(zhǔn)的Javadoc標(biāo)記按以下順序出現(xiàn)：@param, @return, @throws, @deprecated, 前面這4種標(biāo)記如果出現(xiàn)津畸，描述都不能為空肉拓。當(dāng)描述無法在一行中容納梳庆，連續(xù)行需要至少再縮進(jìn)4個空格膏执。

7.2 摘要片段

每個類或成員的Javadoc以一個簡短的摘要片段開始。這個片段是非常重要的欺栗，在某些情況下迟几，它是唯一出現(xiàn)的文本栏笆，比如在類和方法索引中蛉加。

這只是一個小片段，可以是一個名詞短語或動詞短語厂抽，但不是一個完整的句子筷凤。它不會以A {@code Foo} is a...或This method returns...開頭, 它也不會是一個完整的祈使句户盯，如Save the record...莽鸭。然而，由于開頭大寫及被加了標(biāo)點(diǎn)足淆，它看起來就像是個完整的句子巧号。

Tip：一個常見的錯誤是把簡單的Javadoc寫成/** @return the customer ID */姥闭，這是不正確的棚品。它應(yīng)該寫成/** Returns the customer ID. */。

7.3 哪里需要使用Javadoc

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

7.3.1 例外：不言自明的方法

對于簡單明顯的方法如getFoo掷空，Javadoc是可選的(即囤锉，是可以不寫的)官地。這種情況下除了寫“Returns the foo”，確實(shí)也沒有什么值得寫了拧粪。

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

Tip：如果有一些相關(guān)信息是需要讀者了解的蠢熄，那么以上的例外不應(yīng)作為忽視這些信息的理由签孔。例如窘行，對于方法名getCanonicalName罐盔，就不應(yīng)該忽視文檔說明，因?yàn)樽x者很可能不知道詞語canonical name指的是什么捏顺。

7.3.2 例外：重寫

如果一個方法重寫了超類中的方法草丧，那么Javadoc并非必需的莹桅。

7.3.3 非必需的Javadoc

其他類和成員可以根據(jù)需要或需要使用 Javadoc诈泼。

每當(dāng)一個實(shí)現(xiàn)注釋被用來定義一個類或成員的總體目標(biāo)或行為時铐达，該注釋就被編寫為 Javadoc (使用 / * *)瓮孙。

非必需的 Javadoc 并不嚴(yán)格要求遵循第7.1.2杭抠、7.1.3和7.2節(jié)的格式化規(guī)則偏灿，盡管當(dāng)然推薦這樣做。

參考

https://github.com/google/styleguide

https://google.github.io/styleguide/javaguide.html

https://www.cnblogs.com/Juli/p/7309450.html

Google Java編程風(fēng)格規(guī)范(2020年4月原版翻譯)