阿里Java編程規(guī)約【三】代碼格式

1. 【強(qiáng)制】如果大括號(hào)內(nèi)為空，簡(jiǎn)潔地寫成{}即可，大括號(hào)中間無(wú)需換行和空格；如果是非空代碼塊，則：
1）左大括號(hào)前不換行。
2）左大括號(hào)后換行。
3）右大括號(hào)前換行。
4）右大括號(hào)后還有 else 等代碼則不換行；表示終止的右大括號(hào)后必須換行。

2. 【強(qiáng)制】左小括號(hào)和右邊相鄰字符之間不需要空格；右小括號(hào)和左邊相鄰字符之間也不需要空格；而左大 括號(hào)前需要加空格。詳見(jiàn)第 5 條下方正例提示。
反例：if(空格 a == b 空格)

3. 【強(qiáng)制】if / for / while / switch / do 等保留字與左右括號(hào)之間都必須加空格。

4. 【強(qiáng)制】任何二目、三目運(yùn)算符的左右兩邊都需要加一個(gè)空格。
說(shuō)明：包括賦值運(yùn)算符 =、邏輯運(yùn)算符 &&、加減乘除符號(hào)等。

5. 【強(qiáng)制】采用 4 個(gè)空格縮進(jìn)，禁止使用 Tab 字符。

說(shuō)明：如使用 Tab 縮進(jìn)，必須設(shè)置 1 個(gè) Tab 為 4 個(gè)空格。
IDEA 設(shè)置 Tab 為 4 個(gè)空格時(shí)，請(qǐng)勿勾選 Use tab character；
Eclipse 設(shè)置中，找到 tab policy 設(shè)置為 Spaces only，Tab size：4，最后必須勾選 insert spaces for tabs

正例：（涉及上述中的 1-5 點(diǎn)）

public static void main(String[] args) {
    // 縮進(jìn) 4 個(gè)空格
    String say = "hello";
    // 運(yùn)算符的左右必須有一個(gè)空格
    int flag = 0;
    // 關(guān)鍵詞 if 與括號(hào)之間必須有一個(gè)空格，括號(hào)內(nèi)的 f 與左括號(hào)，0 與右括號(hào)不需要空格
    if (flag == 0) {
        System.out.println(say);
    }
    // 左大括號(hào)前加空格且不換行；左大括號(hào)后換行
    if (flag == 1) {
        System.out.println("world");
        // 右大括號(hào)前換行，右大括號(hào)后有 else，不用換行
    } else {
        System.out.println("ok");
        // 在右大括號(hào)后直接結(jié)束，則必須換行
    }
}

6. 【強(qiáng)制】注釋的雙斜線與注釋內(nèi)容之間有且僅有一個(gè)空格。
正例：

// 這是示例注釋，請(qǐng)注意在雙斜線之后有一個(gè)空格
String commentString = new String("demo");

7. 【強(qiáng)制】在進(jìn)行類型強(qiáng)制轉(zhuǎn)換時(shí)，右括號(hào)與強(qiáng)制轉(zhuǎn)換值之間不需要任何空格隔開(kāi)。

正例：

double first = 3.2D;
int second = (int)first + 2;

8. 【強(qiáng)制】單行字符數(shù)限制不超過(guò) 120 個(gè)，超出需要換行，換行時(shí)遵循如下原則：

1）第二行相對(duì)第一行縮進(jìn) 4 個(gè)空格，從第三行開(kāi)始，不再繼續(xù)縮進(jìn)，參考示例。
2）運(yùn)算符與下文一起換行。
3）方法調(diào)用的點(diǎn)符號(hào)與下文一起換行。
4）方法調(diào)用中的多個(gè)參數(shù)需要換行時(shí)，在逗號(hào)后進(jìn)行。
5）在括號(hào)前不要換行。

正例：

StringBuilder builder = new StringBuilder();
// 超過(guò) 120 個(gè)字符的情況下，換行縮進(jìn) 4 個(gè)空格，并且方法前的點(diǎn)號(hào)一起換行
builder.append("yang").append("hao")...
    .append("chen")...
    .append("chen")...
    .append("chen");

9.【強(qiáng)制】方法參數(shù)在定義和傳入時(shí)，多個(gè)參數(shù)逗號(hào)后面必須加空格。

正例：下例中實(shí)參的 args1 逗號(hào)后邊必須要有一個(gè)空格。

method(args1, args2, args3);

10. 【強(qiáng)制】IDE 的 text file encoding 設(shè)置為 UTF-8；IDE 中文件的換行符使用 Unix 格式，不要使用 Windows 格式。

11.【推薦】單個(gè)方法的總行數(shù)不超過(guò) 80 行。

說(shuō)明：除注釋之外的方法簽名、左右大括號(hào)、方法內(nèi)代碼、空行、回車及任何不可見(jiàn)字符的總行數(shù)不超過(guò) 80 行。

正例：代碼邏輯分清紅花和綠葉，個(gè)性和共性，綠葉邏輯單獨(dú)出來(lái)成為額外方法，使主干代碼更加晰；共性邏輯抽取 成為共性方法，便于復(fù)用和維護(hù)。

12. 【推薦】沒(méi)有必要增加若干空格來(lái)使變量的賦值等號(hào)與上一行對(duì)應(yīng)位置的等號(hào)對(duì)齊。
正例：

int a = 3;
long b = 4L;
float c = 5F;
StringBuffer sb = new StringBuffer();

說(shuō)明：在變量比較多的情況下，是 非常累贅的事情。

13. 【推薦】不同邏輯、不同語(yǔ)義、不同業(yè)務(wù)的代碼之間插入一個(gè)空行，分隔開(kāi)來(lái)以提升可讀性。
說(shuō)明：任何情形，沒(méi)有必要插入多個(gè)空行進(jìn)行隔開(kāi)。

額外加餐

文檔注釋標(biāo)簽

Java 語(yǔ)言規(guī)范還定義了一種特殊的注釋，叫文檔注釋（doc comment），這種注釋用于編寫代碼 API 的文檔。

  • 以 /** 開(kāi)頭（不是通常使用的 /*），以 */ 結(jié)尾。文檔注釋放在類型或成員定義的前面，其中的內(nèi)容是那個(gè)類型或成員的文檔。
  • 文檔注釋的描述性內(nèi)容可以包含簡(jiǎn)單的 HTML 標(biāo)記標(biāo)簽，例如：<i> 用于強(qiáng)調(diào)，<code> 用于顯示類、方法和字段的名稱，<pre> 用于顯示多行代碼示例。除此之外，也可以包含 <p> 標(biāo)簽，把說(shuō)明分成多個(gè)段落；還可以使用 <ul> 和 <li> 等相關(guān)標(biāo)簽，顯示無(wú)序列表等結(jié)構(gòu)。不過(guò)，要記住，你編寫的內(nèi)容會(huì)嵌入復(fù)雜的大型 HTML 文檔，因此，文檔注釋不能包含 HTML 主結(jié)構(gòu)標(biāo)簽，例如 <h2> 和 <hr>，以防影響那個(gè)大型 HTML 文檔的結(jié)構(gòu)。

  • @author name
    添加一個(gè)“Author:”條目，內(nèi)容是指定的名字。每個(gè)類和接口定義都應(yīng)該使用這個(gè)標(biāo)簽，但單個(gè)方法和字段一定不能使用。如果一個(gè)類有多位作者，在相鄰的幾行中使用多個(gè) @author 標(biāo)簽。

  • @version text
    插入一個(gè)“Version:”條目，內(nèi)容是指定的文本。例如：
    @version 1.32, 08/26/04
    每個(gè)類和接口的文檔注釋中都應(yīng)該包含這個(gè)標(biāo)簽，但單個(gè)方法和字段不能使用。這個(gè)標(biāo)簽經(jīng)常和支持自動(dòng)排序版本號(hào)的版本控制系統(tǒng)一起使用，例如 git、Perforce 或 SVN。

  • @param parameter-name description
    把指定的參數(shù)及其說(shuō)明添加到當(dāng)前方法的“Parameters:”區(qū)域。在方法和構(gòu)造方法的文檔注釋中，每個(gè)參數(shù)都要使用一個(gè) @param 標(biāo)簽列出，而且應(yīng)該按照參數(shù)傳入方法的順序排列。這個(gè)標(biāo)簽只能出現(xiàn)在方法或構(gòu)造方法的文檔注釋中。

  • @return description
    插入一個(gè)“Returns:”區(qū)域，內(nèi)容是指定的說(shuō)明。每個(gè)方法的文檔注釋中都應(yīng)該使用這個(gè)標(biāo)簽，除非方法返回 void，或者是構(gòu)造方法。為了保持簡(jiǎn)短，建議使用句子片段。

@return <code>true</code>：成功插入
        <code>false</code>：列表中已經(jīng)包含要插入的對(duì)象

  • @exception full-classname description
    添加一個(gè)“Throws:”條目，內(nèi)容是指定的異常名稱和說(shuō)明。方法和構(gòu)造方法的文檔注釋應(yīng)該為 throws 子句中的每個(gè)已檢異常編寫一個(gè) @exception 標(biāo)簽。如果方法的用戶基于某種原因想捕獲當(dāng)前方法拋出的未檢異常（即 RuntimeException 的子類），@exception 標(biāo)簽也可以為這些未檢異常編寫文檔。如果方法能拋出多個(gè)異常，要在相鄰的幾行使用多個(gè) @exception 標(biāo)簽，而且按照異常名稱的字母表順序排列。這個(gè)標(biāo)簽只能出現(xiàn)在方法和構(gòu)造方法的文檔注釋中。

  • @throws full-classname description
    這個(gè)標(biāo)簽是 @exception 標(biāo)簽的別名。

  • @see reference
    添加一個(gè)“See Also:”條目，內(nèi)容是指定的引用。這個(gè)標(biāo)簽可以出現(xiàn)在任何文檔注釋中。

  • @deprecated explanation
    這個(gè)標(biāo)簽指明隨后的類型或成員棄用了，應(yīng)該避免使用。javadoc 會(huì)在文檔中添加一個(gè)明顯的“Deprecated”條目，內(nèi)容為指定的 explanation 文本。這個(gè)文本應(yīng)該說(shuō)明這個(gè)類或成員從何時(shí)開(kāi)始棄用，如果可能的話，還要推薦替代的類或成員，并且添加指向替代的類或成員的鏈接。
    一般情況下，javac 會(huì)忽略所有注釋，但 @deprecated 標(biāo)簽是個(gè)例外。如果文檔注釋中有這個(gè)標(biāo)簽，編譯器會(huì)在生成的類文件中注明棄用信息，提醒其他類，這個(gè)功能已經(jīng)棄用。

  • @since version
    指明類型或成員何時(shí)添加到 API 中。這個(gè)標(biāo)簽后面應(yīng)該跟著版本號(hào)或其他形式的版本信息。例如：@since JDK1.0
    每個(gè)類型的文檔注釋都應(yīng)該包含一個(gè) @since 標(biāo)簽；類型初始版本之后添加的任何成員，都要在其文檔注釋中加上 @since 標(biāo)簽。

行內(nèi)文檔注釋標(biāo)簽

只要能使用 HTML 文本的地方都可以使用行內(nèi)標(biāo)簽。因?yàn)檫@些標(biāo)簽直接出現(xiàn)在 HTML 文本流中，所以要使用花括號(hào)把標(biāo)簽中的內(nèi)容和周圍的 HTML 文本隔開(kāi)。javadoc 支持的行內(nèi)標(biāo)簽包括如下幾個(gè)。

  • {@link reference }
    {@link}標(biāo)簽和 @see標(biāo)簽的作用類似，但 @see 標(biāo)簽是在專門的“See Also:”區(qū)域放一個(gè)指向引用的鏈接，而 {@link}標(biāo)簽在行內(nèi)插入鏈接。在文檔注釋中，只要能使用 HTML 文本的地方都可以使用{@link} 標(biāo)簽。
    例如： @param regexp 搜索時(shí)使用的正則表達(dá)式。這個(gè)字符串參數(shù)使用的句法必須符合{@link java.util.regex.Pattern}制定的規(guī)則。

  • {@linkplain reference }
    {@linkplain}標(biāo)簽和 {@link} 標(biāo)簽的作用類似，不過(guò)，在 {@linkplain} 標(biāo)簽生成的鏈接中，鏈接文字使用普通的字體，而 {@link} 標(biāo)簽使用代碼字體。如果 reference 包含要鏈接的 feature 和指明鏈接替代文本的 label，就要使用 {@linkplain} 標(biāo)簽。

  • {@inheritDoc}
    如果一個(gè)方法覆蓋了超類的方法，或者實(shí)現(xiàn)了接口中的方法，那么這個(gè)方法的文檔注釋可以省略一些內(nèi)容，讓 javadoc 自動(dòng)從被覆蓋或被實(shí)現(xiàn)的方法中繼承。{@inheritDoc} 標(biāo)簽可以繼承單個(gè)標(biāo)簽的文本，還能在繼承的基礎(chǔ)上再添加一些說(shuō)明。繼承單個(gè)標(biāo)簽的方式如下：

@param index @{inheritDoc}
@return @{inheritDoc}

  • {@docRoot}
    這個(gè)行內(nèi)標(biāo)簽沒(méi)有參數(shù)，javadoc生成文檔時(shí)會(huì)把它替換成文檔的根目錄。這個(gè)標(biāo)簽在引用外部文件的超鏈接中很有用，例如引用一張圖片或者一份版權(quán)聲明：
    <img src="{@docroot}/images/logo.gif">這份資料受<a href="{@docRoot}/legal.html">版權(quán)保護(hù)</a>。

  • {@literal text }
    這個(gè)行內(nèi)標(biāo)簽按照字面形式顯示text，text 中的所有 HTML 都會(huì)轉(zhuǎn)義，而且所有javadoc標(biāo)簽都會(huì)被忽略。雖然不保留空白格式，但仍適合在 <pre> 標(biāo)簽中使用。

  • {@code text }
    這個(gè)標(biāo)簽和 {@literal} 標(biāo)簽的作用類似，但會(huì)使用代碼字體顯示 text 的字面量。

  • {@value}
    沒(méi)有參數(shù)的 {@value} 標(biāo)簽在 static final 字段的文檔注釋中使用，會(huì)被替換成當(dāng)前字段的常量值。

  • {@value reference }
    這種 {@value}標(biāo)簽的變體有一個(gè)reference參數(shù)，指向一個(gè)static final字段，會(huì)被替換成指定字段的常量值。

包的文檔注釋

  • javadoc 會(huì)在包所在的目錄（存放包中各個(gè)類的源碼）中需找一個(gè)名為 package.html 的文件，這個(gè)文件中的內(nèi)容就是包的文檔。
  • package.html 文件可以包含簡(jiǎn)單的 HTML 格式文檔，也可以使用 @see、@link、@deprecated 和 @since 標(biāo)簽。因?yàn)?package.html 不是 Java 源碼文件，所以其中的文檔應(yīng)該是 HTML，而不能是 Java 注釋（即不能包含在 /** 和 */ 之間）。最后，在 package.html 文件中，所有 @see 和 @link 標(biāo)簽都必須使用完全限定的類名。

類成員的順序

這并沒(méi)有唯一的正確解決方案，但如果都使用一致的順序?qū)?huì)提高代碼的可讀性，推薦使用如下排序：

  1. 常量
  2. 字段
  3. 構(gòu)造函數(shù)
  4. 重寫函數(shù)和回調(diào)
  5. 公有函數(shù)
  6. 私有函數(shù)
  7. 內(nèi)部類或接口

舉例如下：

public class MainActivity extends Activity {
    private static final String TAG = MainActivity.class.getSimpleName();
    private String mTitle;
    private TextView mTextViewTitle;
    @Override
    public void onCreate() {
        ...
    }
    public void setTitle(String title) {
        mTitle = title;
    }
    private void setUpView() {
        ...
    }
    static class AnInnerClass {
    }
}

如果類繼承于 Android 組件（例如 Activity 或 Fragment），那么把重寫函數(shù)按照他們的生命周期進(jìn)行排序是一個(gè)非常好的習(xí)慣，例如，Activity 實(shí)現(xiàn)了 onCreate()、onDestroy()、onPause()、onResume()，它的正確排序如下所示：

public class MainActivity extends Activity {
    // Order matches Activity lifecycle
    @Override
    public void onCreate() {...}
    @Override
    public void onResume() {...}
    @Override
    public void onPause() {...}
    @Override
    public void onDestroy() {...}
}

參考

  1. 2022 Java開(kāi)發(fā)手冊(cè)(黃山版).pdf
  2. Android 開(kāi)發(fā)規(guī)范（完結(jié)版） | Blankj's Blog https://blankj.com/2017/03/08/android-standard-dev-final/
最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容