[转载] Google Java代码规范
參考鏈接： 使用Java計(jì)算文本文件txt中的行數(shù)/單詞數(shù)/字符數(shù)和段落數(shù)
原文地址：https://google.github.io/styleguide/javaguide.html
GIthub上GoogleCode風(fēng)格的配置文件（支持Eclipse IDE和IntelliJ IDE）：https://github.com/codeset/google-java-styleguide
1簡(jiǎn)介
?
本文檔作為Java編程語(yǔ)言中源代碼的Google編碼標(biāo)準(zhǔn)的完整定義。當(dāng)且僅當(dāng)它遵守本文中的規(guī)則時(shí)，Java源文件被描述為在Google Style中。
與其他編程風(fēng)格指南一樣，所涵蓋的問(wèn)題不僅包括格式化的美學(xué)問(wèn)題，也包括其他類型的約定或編碼標(biāo)準(zhǔn)。但是，本文檔主要關(guān)注我們普遍遵循的快速規(guī)則 ，并避免提供不可明確強(qiáng)制執(zhí)行的建議（無(wú)論是通過(guò)人工還是工具）。
1.1術(shù)語(yǔ)注釋
在本文件中，除非另有說(shuō)明：
術(shù)語(yǔ)類被包含性地用于表示“普通”類，枚舉類，接口或注釋類型（ @interface ）。術(shù)語(yǔ)成員 （類的）包含地用于表示嵌套類，字段，方法或構(gòu)造函數(shù) ;即除了初始化器和注釋之外的類的所有頂級(jí)內(nèi)容。術(shù)語(yǔ)注釋總是指實(shí)現(xiàn)注釋。 我們不使用短語(yǔ)“文檔注釋”，而是使用通用術(shù)語(yǔ)“Javadoc”。
其他“術(shù)語(yǔ)說(shuō)明”將偶爾出現(xiàn)在整個(gè)文檔中。
1.2指南說(shuō)明
本文檔中的示例代碼是非規(guī)范的 。 也就是說(shuō)，雖然示例是在Google風(fēng)格，但它們可能不會(huì)說(shuō)明代表代碼的唯一時(shí)尚的方式。 示例中所做的可選格式選擇不應(yīng)作為規(guī)則強(qiáng)制執(zhí)行。
2源文件基礎(chǔ)
2.1文件名
源文件名由其包含的頂級(jí)類（其中包含正好一個(gè) ）的區(qū)分大小寫的名稱，以及.java擴(kuò)展名組成。
2.2文件編碼：UTF-8
源文件以UTF-8編碼。
2.3特殊字符
2.3.1空格字符
除了行終止符序列， ASCII水平空格字符 （ 0x20 ）是在源文件中任何位置出現(xiàn)的唯一的空格字符。這意味著：
字符串和字符文字中的所有其他空白字符都將被轉(zhuǎn)義。制表符不用于縮進(jìn)。
2.3.2特殊轉(zhuǎn)義序列
對(duì)于具有特殊轉(zhuǎn)義序列 （ \b ，\t ，\n ，\f ，\r ，\" ，\'和\\ ）的任何字符，使用該序列而不是相應(yīng)的八進(jìn)制Unicode（例如\u000a ）轉(zhuǎn)義。
2.3.3非ASCII字符
對(duì)于剩余的非ASCII字符，使用實(shí)際的Unicode字符（例如∞ ）或等效的Unicode轉(zhuǎn)義（例如\u221e ）。 選擇僅取決于哪些使得代碼更容易閱讀和理解 ，盡管Unicode轉(zhuǎn)義字符串字面值和注釋強(qiáng)烈阻止。
提示：在Unicode脫機(jī)情況下，偶爾即使使用實(shí)際的Unicode字符，解釋性注釋也會(huì)非常有用。
例子：
例討論String unitAbbrev="μs";最好：完全清楚，即使沒(méi)有評(píng)論。String unitAbbrev="\u03bcs";// "μs"允許，但沒(méi)有理由這樣做。String unitAbbrev="\u03bcs";// Greek letter mu, "s"允許，但尷尬，容易犯錯(cuò)誤。String unitAbbrev = "\u03bcs";差：讀者不知道這是什么。return'\ufeff'+ content;// byte order mark良好：對(duì)不可打印字符使用轉(zhuǎn)義，如有必要，請(qǐng)注釋。
提示：不要因?yàn)槟承┏绦蚩赡軣o(wú)法正確處理非ASCII字符而使您的代碼變得不可讀。如果這應(yīng)該發(fā)生，那些程序被打破 ，它們必須是固定的 。
?
?
3源文件結(jié)構(gòu)
?
?源文件由以下順序組成 ：
?許可或版權(quán)信息（如果存在）軟件包語(yǔ)句導(dǎo)入語(yǔ)句完全一個(gè)頂級(jí)類
?
正好一個(gè)空白線分隔存在的每個(gè)部分。
3.1許可或版權(quán)信息（如果存在）
如果許可證或版權(quán)信息屬于文件，則它屬于此處。
3.2包裝聲明
包語(yǔ)句不是線包裝 。 列限制（第4.4節(jié)， 列限制：100 ）不適用于包語(yǔ)句。
?
?
3.3導(dǎo)入語(yǔ)句
3.3.1無(wú)通配符導(dǎo)入
不使用靜態(tài)或其他方式的通配符導(dǎo)入 。
3.3.2沒(méi)有線包裝
導(dǎo)入語(yǔ)句不是線包裝的 。 列限制（第4.4節(jié)， 列限制：100 ）不適用于import語(yǔ)句。
3.3.3訂購(gòu)和間距
導(dǎo)入順序如下：
在單個(gè)塊中的所有靜態(tài)導(dǎo)入。所有非靜態(tài)導(dǎo)入在單個(gè)塊中。
如果存在靜態(tài)和非靜態(tài)導(dǎo)入，則單個(gè)空白行分隔兩個(gè)塊。 import語(yǔ)句之間沒(méi)有其他空行。
在每個(gè)塊中，導(dǎo)入的名稱以ASCII排序順序顯示。 （ 注意：這與以ASCII排序順序的import 語(yǔ)句不同 ，因?yàn)?#39;。'排在';'前面）。
3.3.4沒(méi)有類的靜態(tài)導(dǎo)入
靜態(tài)導(dǎo)入不用于靜態(tài)嵌套類。 它們以正常進(jìn)口進(jìn)口。
3.4類聲明
?
?
3.4.1完全一個(gè)頂級(jí)類聲明
每個(gè)頂級(jí)類都駐留在自己的源文件中。
?
?
3.4.2類內(nèi)容的排序
為類的成員和初始化器選擇的順序可以對(duì)可學(xué)習(xí)性有很大的影響。 然而，沒(méi)有一個(gè)正確的方法來(lái)做到這一點(diǎn); 不同的類可以以不同的方式對(duì)其內(nèi)容進(jìn)行排序。
重要的是每個(gè)類使用一些邏輯順序 ，維護(hù)者可以解釋如果問(wèn)。例如，新方法不僅習(xí)慣性地添加到類的末尾，因?yàn)檫@將產(chǎn)生“按照添加日期的順序”排序，這不是邏輯排序。
?
?
3.4.2.1重載：從不分裂
當(dāng)一個(gè)類有多個(gè)構(gòu)造函數(shù)或者多個(gè)同名的方法時(shí)，這些順序出現(xiàn)，中間沒(méi)有其他代碼（甚至不是私有成員）。
4格式化
術(shù)語(yǔ)注意： 塊狀構(gòu)造指的是類，方法或構(gòu)造函數(shù)的主體。注意，通過(guò)關(guān)于數(shù)組初始化器的第4.8.3.1節(jié)，任何數(shù)組初始化器都可以被視為塊狀構(gòu)造。
?
?
4.1大括號(hào)
4.1.1在可選時(shí)使用括號(hào)
大括號(hào)與if ，else ，for ，do和while語(yǔ)句一起使用，即使主體為空或僅包含單個(gè)語(yǔ)句。
4.1.2非空塊：K＆R風(fēng)格
大括號(hào)遵循Kernighan和Ritchie風(fēng)格（“ 埃及括號(hào) ”）用于非空塊和塊狀結(jié)構(gòu)：
在大括號(hào)前沒(méi)有換行符。開頭大括號(hào)后的換行符。換行前的換行。關(guān)閉大括號(hào)后的換行符， 僅當(dāng)該大括號(hào)終止語(yǔ)句或終止方法，構(gòu)造函數(shù)或命名類的主體時(shí)。例如，如果后面跟著else或逗號(hào)，那么大括號(hào)后面沒(méi)有換行符。
例子：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?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é)“枚舉類”中給出。
?
?
4.1.3空塊：可能簡(jiǎn)潔
空塊或塊狀構(gòu)造可以是K＆R樣式（如第4.1.2節(jié)所述）。或者，它可以在打開后立即關(guān)閉，在（{} ）之間沒(méi)有字符或換行符，除非它是多塊語(yǔ)句的一部分 （直接包含多個(gè)塊：if/else或try/catch/finally）。
例子：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?// This is acceptable? ? ?void doNothing() {}? ? ?// This is equally acceptable? ?void doNothingElse() {? ?}??
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?// This is not acceptable: No concise empty blocks in a multi-block statement? ?try {? ? ?doSomething();? ?} catch (Exception e) {}??
?
?
4.2塊縮進(jìn)：+2個(gè)空格
每次打開新的塊或塊狀構(gòu)造時(shí)，縮進(jìn)增加兩個(gè)空格。 當(dāng)塊結(jié)束時(shí)，縮進(jìn)返回到上一縮進(jìn)級(jí)別。 縮進(jìn)級(jí)別適用于整個(gè)塊中的代碼和注釋。 （請(qǐng)參見第4.1.2節(jié)“ 非空塊：K＆R Style”中的示例。）
4.3每行一個(gè)語(yǔ)句
每個(gè)語(yǔ)句后面都有換行符。
?
?
4.4列限制：100
Java代碼的列限制為100個(gè)字符。 除非如下所述，否則超過(guò)此限制的任何行都必須被換行，如第4.5節(jié)“ 換行”中所述。
例外：
無(wú)法遵守列限制的行（例如，Javadoc中的長(zhǎng)URL或長(zhǎng)JSNI方法引用）。package和import語(yǔ)句（見第3.2節(jié)包語(yǔ)句和3.3導(dǎo)入語(yǔ)句 ）。注釋中的命令行可以剪切并粘貼到shell中。
4.5線包裝
術(shù)語(yǔ)注意：當(dāng)可能合法占用單個(gè)行的代碼被分為多行時(shí)，此活動(dòng)稱為行換行 。
沒(méi)有全面的，確定性的公式，顯示每種情況下如何包裝。 通常有幾種有效的方法來(lái)?yè)Q行同一段代碼。
注意：雖然換行的典型原因是為了避免溢出列限制，即使在事實(shí)上符合列限制的代碼也可能由作者自行決定。
提示：提取方法或局部變量可以解決問(wèn)題，而不需要換行。
4.5.1打破的地方
線包裝的主要指令是：更喜歡在更高的語(yǔ)法層面打破。 也：
當(dāng)在非賦值運(yùn)算符處斷開一行時(shí)，中斷在符號(hào)之前 。 （請(qǐng)注意，這與其他語(yǔ)言（例如C ++和JavaScript）在Google樣式中使用的做法不同）。
? 這也適用于以下“類似運(yùn)算符”的符號(hào)：
? ? 點(diǎn)分隔符（ . ）方法引用（::）的兩個(gè)冒號(hào)類型邊界中的<TextendsFoo&Bar>符號(hào)（<TextendsFoo&Bar> ）在catch塊中的一個(gè)管道（ catch (FooException|BarException e) ）。當(dāng)一個(gè)行在賦值操作符中斷時(shí)，中斷通常出現(xiàn)在符號(hào)之后 ，但是任何一種方式都是可以接受的。
? 這也適用于增強(qiáng)型for （“foreach”）語(yǔ)句中的“賦值運(yùn)算符”冒號(hào)。方法或構(gòu)造函數(shù)名稱附加到它后面的開括號(hào)（ ( ））。逗號(hào)（ , ）保持附加到它前面的令牌。在lambda中，一行從不會(huì)被折斷，除了如果lambda的主體由單個(gè)非支持表達(dá)式組成，則可能會(huì)在箭頭之后立即出現(xiàn)中斷。例子：
??
? ?
? ??
? ? ?[java]?
? ? ?view plain
? ? ? copy
? ? ?
? ? ?
? ??
? ?
? ?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)連續(xù)線至少+4個(gè)空格
當(dāng)換行時(shí)，第一行（每個(gè)連續(xù)行 ）后面的每一行從原始行縮進(jìn)至少+4。
當(dāng)存在多個(gè)連續(xù)線時(shí)，根據(jù)需要，壓痕可以變化超過(guò)+4。 一般來(lái)說(shuō)，當(dāng)且僅當(dāng)它們以句法并行元素開頭時(shí)，兩個(gè)連續(xù)行使用相同的縮進(jìn)級(jí)別。
關(guān)于水平對(duì)齊的第4.6.3節(jié)闡述了使用可變數(shù)量的空間將某些令牌與先前的行對(duì)齊的不鼓勵(lì)做法。
4.6空白
4.6.1垂直空白
將顯示一個(gè)空白行：
在類的連續(xù)成員或初始化器之間：字段，構(gòu)造函數(shù)，方法，嵌套類，靜態(tài)初始化器和實(shí)例初始化器。
? 異常：兩個(gè)連續(xù)字段之間的空行（它們之間沒(méi)有其他代碼）是可選的。這樣的空白行根據(jù)需要用于創(chuàng)建字段的邏輯分組 。異常：枚舉常量之間的空行在第4.8.1節(jié)中介紹 。在語(yǔ)句之間， 根據(jù)需要將代碼組織成邏輯子部分。可選地在第一個(gè)成員或初始化程序之前，或在類的最后一個(gè)成員或初始化程序之后（既不鼓勵(lì)也不鼓勵(lì)）。根據(jù)本文檔其他部分的要求（如第3節(jié)， 源文件結(jié)構(gòu)和第3.3節(jié)， 導(dǎo)入語(yǔ)句 ）。
允許多個(gè)連續(xù)的空行，但不需要（或鼓勵(lì)）。
4.6.2水平空白
除了語(yǔ)言或其他樣式規(guī)則所要求的之外，除了文字，注釋和Javadoc之外，單個(gè)ASCII空間也僅出現(xiàn)在以下位置。
將任何保留字（例如if ，for或catch ）從該行后面的開括號(hào)（( ））中分離將任何保留字（例如else或catch ）與該行上的關(guān)閉大括號(hào)（} ）分隔開在任何打開的大括號(hào)（ { ）之前，有兩個(gè)例外：
? @SomeAnnotation({a, b}) （不使用空格）String[][] x={{"foo"}};（{{下面第8項(xiàng)）之間不需要空格，在任何二進(jìn)制或三元運(yùn)算符的兩側(cè)。 這也適用于以下“類似運(yùn)算符”的符號(hào)：
? 連接符類型的連接<TextendsFoo&Bar> ：<TextendsFoo&Bar>用于處理多個(gè)異常的catch塊的管道： catch (FooException|BarException e)冒號(hào)（：）在增強(qiáng)型for （“foreach”）語(yǔ)句中l(wèi)ambda表達(dá)式中的箭頭： (String str)-> str.length()但不是
? 一個(gè)方法引用的兩個(gè)冒號(hào)（::），它寫得像Object::toString點(diǎn)分隔符（ . ），它寫作object.toString()后,:;或右括號(hào)（) ）在開始結(jié)束行注釋的雙斜線（ // ）的兩側(cè)。 這里，允許多個(gè)空格，但不是必需的。在一個(gè)聲明的類型和變量之間： List<String> list可選只在數(shù)組初始值設(shè)定符的兩個(gè)大括號(hào)內(nèi)
? newint[]{5,6}和newint[]{5,6}都是有效的
此規(guī)則從不解釋為在行的開始或結(jié)束處要求或禁止額外的空間;
?
它只涉及內(nèi)部空間。
?
4.6.3水平對(duì)齊：從不需要
術(shù)語(yǔ)注意： 水平對(duì)齊是在代碼中添加可變數(shù)量的附加空間的做法，目的是使某些令牌直接顯示在之前行上的某些其他令牌下方。
這種做法是允許的，但Google風(fēng)格從不需要 。 甚至不需要在已經(jīng)使用的地方保持水平對(duì)準(zhǔn)。
這里是一個(gè)沒(méi)有對(duì)齊的例子，然后使用對(duì)齊：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?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??
?
?
提示：
對(duì)齊可以幫助可讀性，但它會(huì)為以后的維護(hù)帶來(lái)問(wèn)題。
考慮一個(gè)需要觸摸只有一行的未來(lái)變化。
這種變化可能會(huì)使以前令人愉快的格式化失敗，這是允許的 。
更頻繁地，它提示編碼器（也許你）調(diào)整附近線上的空白，可能觸發(fā)級(jí)聯(lián)系列的重新格式化。
那一行的變化現(xiàn)在有一個(gè)“爆炸半徑”。
這可能在最壞的情況下導(dǎo)致無(wú)意義的繁忙工作，但最多仍會(huì)破壞版本歷史信息，減慢審閱者和加劇合并沖突。
?
?
?
4.7分組括號(hào)：推薦
可選的分組括號(hào)只有在作者和審稿人同意沒(méi)有合理的機(jī)會(huì)，沒(méi)有他們的代碼將被誤解，他們也不會(huì)使代碼更容易閱讀。假設(shè)每個(gè)讀取器都具有存儲(chǔ)的整個(gè)Java運(yùn)算符優(yōu)先級(jí)表是不合理的。
4.8特定構(gòu)建體
4.8.1枚舉類
在遵循枚舉常量的每個(gè)逗號(hào)后，換行符是可選的。 還允許附加空行（通常只有一個(gè)）。 這是一個(gè)可能性：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?private enum Answer {? ? ? YES {? ? ? @Override public String toString() {? ? ? ? return "yes";? ? ? }? ? },? ? ? NO,? ? MAYBE? }??
?
?
沒(méi)有方法和沒(méi)有文檔的常量的枚舉類可以可選地被格式化為數(shù)組初始化器（見關(guān)于數(shù)組初始化器的第4.8.3.1節(jié)）。
?
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?privete enum Clothes{CLUBS，HEARTS，SPADES，DIAMONDS}??
?
?
由于枚舉類是類 ，因此適用于格式化類的所有其他規(guī)則。
?
?
?
?
4.8.2變量聲明
4.8.2.1每個(gè)聲明一個(gè)變量
每個(gè)變量聲明（字段或本地）只聲明一個(gè)變量：聲明如int a, b;不使用。
4.8.2.2需要時(shí)聲明
局部變量不習(xí)慣地在它們的包含塊或塊狀構(gòu)造的開始處聲明。 相反，局部變量被聲明為接近它們首次使用的點(diǎn)（在原因內(nèi)），以最小化它們的范圍。 局部變量聲明通常具有初始化器，或者在聲明之后立即初始化。
4.8.3數(shù)組
4.8.3.1數(shù)組初始化器：可以是“塊狀”
任何數(shù)組初始化器可以可選地被格式化為好像它是“塊狀構(gòu)造”。 例如，以下都是有效的（ 不是詳盡的列表）：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?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沒(méi)有C樣式數(shù)組聲明
方括號(hào)形成類型的一部分，而不是變量： String[] args ，而不是String args[] 。
4.8.4切換語(yǔ)句
術(shù)語(yǔ)注意： 交換機(jī)塊的大括號(hào)內(nèi)是一個(gè)或多個(gè)語(yǔ)句組 。每個(gè)語(yǔ)句組由一個(gè)或多個(gè)開關(guān)標(biāo)簽 （無(wú)論是caseFOO:或default: ：）組成，后跟一個(gè)或多個(gè)語(yǔ)句。
4.8.4.1縮進(jìn)
與任何其他塊一樣，開關(guān)塊的內(nèi)容縮進(jìn)+2。
在切換標(biāo)簽之后，有一個(gè)換行符，縮進(jìn)級(jí)別增加+2，就像打開一個(gè)塊一樣。 以下開關(guān)標(biāo)簽返回到上一縮進(jìn)級(jí)別，如同一個(gè)塊已關(guān)閉。
?
?
4.8.4.2通過(guò)：評(píng)論
在開關(guān)塊內(nèi)，每個(gè)語(yǔ)句組都會(huì)突然終止（使用break ，continue ，return或thrown異常），或者標(biāo)記有注釋，指示執(zhí)行將繼續(xù)或可能繼續(xù)到下一個(gè)語(yǔ)句組。任何傳達(dá)墮落想法的評(píng)論都是足夠的（通常// fall through ）。在開關(guān)組的最后一個(gè)語(yǔ)句組中不需要此特殊注釋。例：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?switch (input) {? ? case 1:? ? case 2:? ? ? prepareOneOrTwo();? ? ? // fall through? ? case 3:? ? ? handleOneTwoOrThree();? ? ? break;? ? default:? ? ? handleLargeNumber(input);? }??
?
?
注意，在
case1:
之后不需要注釋，只在語(yǔ)句組的末尾。
?
4.8.4.3 default情況存在
每個(gè)switch語(yǔ)句包括一個(gè)default語(yǔ)句組，即使它不包含代碼。
?
?
4.8.5注釋
應(yīng)用于類，方法或構(gòu)造函數(shù)的注釋立即出現(xiàn)在文檔塊之后，并且每個(gè)注釋都列在其自己的行（即每行一個(gè)注釋）上。這些換行符不構(gòu)成換行（第4.5節(jié)，換行 ），因此縮進(jìn)級(jí)別不會(huì)增加。 例：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?@Override? @Nullable? public String getNameIfPresent() { ... }??
?
?
異常：
?
單個(gè)
無(wú)參數(shù)注釋
可以
改為與簽名的第一行一起出現(xiàn)，例如：
?
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?@Override public int hashCode() { ... }??
?
?
應(yīng)用于字段的注釋也會(huì)立即出現(xiàn)在文檔塊之后，但在這種情況下，?
多個(gè)
注釋（可能已參數(shù)化）可能會(huì)列在同一行上;
例如：
?
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?@Partial @Mock DataLoader loader;??
?
?
沒(méi)有關(guān)于參數(shù)，局部變量或類型的注釋格式化的具體規(guī)則。
?
?
?
4.8.6評(píng)論
本節(jié)討論實(shí)現(xiàn)注釋 。 Javadoc在第7節(jié)Javadoc中單獨(dú)解決。
任何換行符之前可以有任意空格，然后是實(shí)現(xiàn)注釋。 這樣的注釋使該行非空白。
4.8.6.1塊注釋樣式
塊注釋縮進(jìn)到與周圍代碼相同的級(jí)別。 它們可以是/* ... */ style或// ...樣式。 對(duì)于多行/* ... */注釋，后續(xù)行必須以*與上一行的*對(duì)齊開始。
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?/*? * This is? ? ? ? ? // And so? ? ? ? ? ?/* Or you can? * okay.? ? ? ? ? ? // is this.? ? ? ? ? * even do this. */? ?*/??
?
?
注釋不包含在用星號(hào)或其他字符繪制的框中。
?
提示：在編寫多行注釋時(shí)，如果您希望自動(dòng)代碼格式化程序在必要時(shí)重新?lián)Q行（段落樣式），請(qǐng)使用/* ... */樣式。大多數(shù)格式化程序不會(huì)在// ...樣式注釋塊中重新?lián)Q行。
?
?
4.8.7修飾符
類和成員修飾符（如果存在）按照J(rèn)ava語(yǔ)言規(guī)范建議的順序顯示：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?public protected private abstract default static final transient volatile synchronized native strictfp??
?
?
4.8.8數(shù)字文字
long整數(shù)文字使用大寫L后綴，從不小寫（以避免與數(shù)字1混淆）。例如，3000000000L而不是3000000000l 。
?
?
5命名
5.1所有標(biāo)識(shí)符共有的規(guī)則
標(biāo)識(shí)符只使用ASCII字母和數(shù)字，并且在下面指出的少數(shù)情況下，下劃線。 因此，每個(gè)有效的標(biāo)識(shí)符名稱由正則表達(dá)式\w+匹配。
在Google Style中，特殊的前綴或后綴，如在示例name_ ，mName ，s_name和kName中看到的，不使用。
5.2按標(biāo)識(shí)符類型劃分的規(guī)則
5.2.1包名稱
包名稱都是小寫，連續(xù)的單詞連接在一起（無(wú)下劃線）。 例如， com.example.deepspace ，而不是com.example.deepSpace或com.example.deep_space 。
5.2.2類名
類名寫在UpperCamelCase中 。
類名通常是名詞或名詞短語(yǔ)。 例如， Character或ImmutableList 。接口名稱也可以是名詞或名詞短語(yǔ)（例如，List ），但有時(shí)可以是形容詞或形容詞短語(yǔ)（例如，Readable ）。
沒(méi)有特定的規(guī)則，甚至沒(méi)有成熟的慣例為命名注釋類型。
測(cè)試類從它們正在測(cè)試的類的名稱開始命名，并以Test結(jié)束。例如，HashTest或HashIntegrationTest 。
5.2.3方法名稱
方法名稱寫在lowerCamelCase中 。
方法名稱通常是動(dòng)詞或動(dòng)詞短語(yǔ)。 例如，sendMessage或stop 。
下劃線可能出現(xiàn)在JUnit 測(cè)試方法名稱中以分隔名稱的邏輯組件。 一個(gè)典型的模式是test <MethodUnderTest> _ <state> ，例如testPop_emptyStack 。沒(méi)有一個(gè)正確的方法來(lái)命名測(cè)試方法。
?
?
5.2.4常量名稱
常量名稱使用CONSTANT_CASE ：所有大寫字母，用下劃線分隔的單詞。但什么是常數(shù)，究竟是什么？
常數(shù)是靜態(tài)最終字段，其內(nèi)容是不可變的，并且其方法沒(méi)有可檢測(cè)的副作用。 這包括基元，字符串，不可變類型和不可變類型的不可變集合。 如果任何實(shí)例的observable狀態(tài)可以改變，它不是一個(gè)常量。只是打算從來(lái)不改變對(duì)象是不夠的。例子：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?// 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"};??
?
?
這些名稱通常是名詞或名詞短語(yǔ)。
?
5.2.5非常量字段名稱
非常量字段名（靜態(tài)或其他）寫在lowerCamelCase中 。
這些名稱通常是名詞或名詞短語(yǔ)。 例如，computedValues或index 。
5.2.6參數(shù)名稱
參數(shù)名稱寫在lowerCamelCase中 。
應(yīng)該避免公共方法中的單字符參數(shù)名稱。
5.2.7局部變量名
局部變量名寫在lowerCamelCase中 。
即使最終和不可變的局部變量不被認(rèn)為是常量，并且不應(yīng)該被定型為常量。
5.2.8類型變量名
每個(gè)類型變量都以兩種樣式之一命名：
單個(gè)大寫字母，可選后跟單個(gè)數(shù)字（例如E ，T ，X ，T2 ）用于類的形式的名稱（見第5.2.2節(jié)， 類名 ），后跟大寫字母T （示例：RequestT，FooBarT ）。
?
?
?
5.3駱駝情況：定義
有時(shí)，有一個(gè)以上的合理方式將英語(yǔ)短語(yǔ)轉(zhuǎn)換為駱駝情況，例如當(dāng)首字母縮略詞或不尋常的結(jié)構(gòu)，如“IPv6”或“iOS”存在。為了提高可預(yù)測(cè)性，Google Style指定以下（幾乎）確定性方案。
從名稱的散文形式開始：
將短語(yǔ)轉(zhuǎn)換為純ASCII并刪除任何省略號(hào)。 例如，“Müller算法”可能變成“Muellers算法”。將此結(jié)果劃分為單詞，分割為空格和任何剩余的標(biāo)點(diǎn)符號(hào)（通常為連字符）。
? 推薦：如果任何字詞在常用的情況下已經(jīng)具有常規(guī)的駝峰盒外觀，請(qǐng)將其分為其組成部分（例如，“AdWords”成為“廣告字詞”）。注意，諸如“iOS”這樣的詞本身不是真正的駱駝情況;它違反任何慣例，因此本建議不適用。現(xiàn)在小寫一切 （包括首字母縮略詞），然后大寫只有第一個(gè)字符：
? ...每個(gè)字，產(chǎn)生上駱駝殼 ，或...每個(gè)字除了第一個(gè)，產(chǎn)生較低的駝峰盒最后，將所有單詞連接成單個(gè)標(biāo)識(shí)符。
注意，原始單詞的殼體幾乎完全被忽略。 例子：
散文形式正確不正確“XML HTTP請(qǐng)求”XmlHttpRequestXMLHTTPRequest“新客戶ID”newCustomerIdnewCustomerID“內(nèi)部秒表”innerStopwatchinnerStopWatch“在iOS上支持IPv6？supportsIpv6OnIossupportsIPv6OnIOS“YouTube進(jìn)口商”YouTubeImporterYoutubeImporter *?
*可接受，但不推薦。
注意：某些單詞在英語(yǔ)中有不明確的連字符：例如“nonempty”和“non-empty”都是正確的，所以方法名稱checkNonempty和checkNonEmpty也是正確的。
6編程實(shí)踐
6.1@Override ：始終使用
一個(gè)方法在合法時(shí)用@Override注釋標(biāo)記。這包括重寫超類方法的類方法，實(shí)現(xiàn)接口方法的類方法和重定義超接口方法的接口方法。
異常：當(dāng)父方法為@Deprecated時(shí)，可以省略@Deprecated 。
?
?
6.2捕獲異常：不被忽略
除非如下所述，在響應(yīng)捕獲的異常時(shí)不執(zhí)行任何操作是非常不正確的。 （典型的響應(yīng)是記錄它，或者如果它被認(rèn)為是“不可能”，將其重新拋出為一個(gè)AssertionError 。）
當(dāng)在catch塊中沒(méi)有采取任何行動(dòng)是真正合適的時(shí)候，這是合理的原因在注釋中解釋。
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?try {? ? int i = Integer.parseInt(response);? ? return handleNumericResponse(i);? } catch (NumberFormatException ok) {? ? // it's not numeric; that's fine, just continue? }? return handleTextResponse(response);??
?
?
異常：
在測(cè)試中，如果捕獲的異常名稱為或以
expected
開始，
則
可以忽略捕獲的異常而不進(jìn)行注釋。
以下是一個(gè)非常常見的用于確保測(cè)試中的代碼確實(shí)拋出了預(yù)期類型的??異常的習(xí)語(yǔ)，因此在此不需要注釋。
?
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?try {? ? emptyStack.pop();? ? fail();? } catch (NoSuchElementException expected) {? }??
?
?
6.3靜態(tài)成員：使用類合格
當(dāng)對(duì)靜態(tài)類成員的引用必須限定時(shí)，它將使用該類的名稱限定，而不是該類的類型的引用或表達(dá)式。
?
Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad
?
?
6.4終化劑：未使用
覆蓋Object.finalize是非常罕見的 。
提示：不要這樣做。 如果你絕對(duì)必須，首先閱讀并理解有效的Java項(xiàng)目7，“避免終結(jié)者”，非常仔細(xì)，然后不這樣做。
?
?
7 Javadoc
7.1格式化
7.1.1一般形式
Javadoc塊的基本格式如下例所示：
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?/**? * Multiple lines of Javadoc text are written here,? * wrapped normally...? */? public int method(String p1) { ... }??
?
?
...或在此單行示例中：
?
?
?
?
??
? ?[java]?
? ?view plain
? ? copy
? ?
? ?
??
?
?/** An especially short bit of Javadoc. */??
?
?
基本形式總是可以接受的。?
當(dāng)不存在at-clause時(shí)，單行形式可以被替換，并且Javadoc塊（包括注釋標(biāo)記）的整體可以適合在單個(gè)行上。
?
7.1.2段落
一個(gè)空行（即，僅包含對(duì)齊的前導(dǎo)星號(hào)（ * ）的行）出現(xiàn)在段落之間，并在“at-clause”組（如果存在）之前。每個(gè)段落，但第一個(gè)在緊接第一個(gè)單詞之前有<p>后面沒(méi)有空格。
7.1.3條款
任何使用的標(biāo)準(zhǔn)“at- @deprecated ”都出現(xiàn)在@param@deprecated ，@return@deprecated ， @return ， @param@deprecated這些@deprecated ，并且這四種類型不會(huì)出現(xiàn)空描述。當(dāng)at-clause不適合單個(gè)行時(shí)，連續(xù)行從@的位置縮進(jìn)四（或更多）個(gè)空格。
7.2摘要片段
每個(gè)Javadoc塊以簡(jiǎn)短摘要片段開頭。 這個(gè)片段非常重要：它是出現(xiàn)在某些上下文中的文本的唯一部分，例如類和方法索引。
這是一個(gè)片段 - 一個(gè)名詞短語(yǔ)或動(dòng)詞短語(yǔ)，而不是一個(gè)完整的句子。 它不以A {@code Foo} is a...開頭A {@code Foo} is a... ，或者This method returns... ，也不會(huì)形成一個(gè)完整的命令句，如Save the record.。然而，片段被大寫和標(biāo)點(diǎn)，好像它是一個(gè)完整的句子。
提示：常見的錯(cuò)誤是以/** @return the customer ID */編寫簡(jiǎn)單的Javadoc。這是不正確的，應(yīng)該更改為/** Returns the customer ID. *//** Returns the customer ID. */ 。
?
?
7.3其中使用Javadoc
至少 ，Javadoc存在于每個(gè)public類以及這種類的每個(gè)public或protected成員，除了下面列出的一些例外。
還可能存在其他Javadoc內(nèi)容，如第7.3.4節(jié)“ 非必需Javadoc”中所述。
7.3.1異常：自明的方法
Javadoc對(duì)于“簡(jiǎn)單的，明顯的”方法（如getFoo是可選的，在真正和真正沒(méi)有什么別的值得說(shuō)，但“返回foo”。
重要提示：引用此例外是不恰當(dāng)?shù)?#xff0c;因?yàn)槭÷粤说湫妥x者可能需要知道的相關(guān)信息。例如，對(duì)于名為getCanonicalName的方法，不要省略其文檔（只有/** Returns the canonical name. */ ），如果典型的讀者可能不知道術(shù)語(yǔ)“canonical name”手段！
7.3.2異常：覆蓋
Javadoc并不總是出現(xiàn)在覆蓋超類型方法的方法上。
7.3.4非必需Javadoc
其他類和成員根據(jù)需要或期望具有Javadoc。
每當(dāng)實(shí)現(xiàn)注釋用于定義類或成員的總體目的或行為時(shí)，該注釋將改為寫為Javadoc（使用/** ）。
非必需的Javadoc不是嚴(yán)格要求遵守第7.1.2,7.1.3和7.2節(jié)的格式化規(guī)則，但當(dāng)然是建議。
總結(jié)
以上是生活随笔為你收集整理的[转载] Google Java代码规范的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： 圆与平面的接触面积_视频：5.3RJ六年
- 下一篇： [转载] Java9发布回顾Java 8