【強(qiáng)制】類、類屬性、類方法的注釋必須使用 Javadoc 規(guī)范，使用/**內(nèi)容*/格式，不得使用

// xxx 方式。

說明：在 IDE 編輯窗口中，Javadoc 方式會(huì)提示相關(guān)注釋，生成 Javadoc 可以正確輸出相應(yīng)注釋；在 IDE

中，工程調(diào)用方法時(shí)，不進(jìn)入方法即可懸浮提示方法、參數(shù)、返回值的意義，提高閱讀效率。

?

【強(qiáng)制】所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋、除了返回值、參數(shù)、

異常說明外，還必須指出該方法做什么事情，實(shí)現(xiàn)什么功能。

說明：對子類的實(shí)現(xiàn)要求，或者調(diào)用注意事項(xiàng)，請一并說明。

?

【強(qiáng)制】所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。

?

【強(qiáng)制】方法內(nèi)部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內(nèi)部多行注釋

使用/* */注釋，注意與代碼對齊。

?

【強(qiáng)制】所有的枚舉類型字段必須要有注釋，說明每個(gè)數(shù)據(jù)項(xiàng)的用途。

?

【推薦】與其“半吊子”英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關(guān)鍵字保

持英文原文即可。

反例：“TCP 連接超時(shí)”解釋成“傳輸控制協(xié)議連接超時(shí)”，理解反而費(fèi)腦筋。

?

【推薦】代碼修改的同時(shí)，注釋也要進(jìn)行相應(yīng)的修改，尤其是參數(shù)、返回值、異常、核心邏

輯等的修改。

說明：代碼與注釋更新不同步，就像路網(wǎng)與導(dǎo)航軟件更新不同步一樣，如果導(dǎo)航軟件嚴(yán)重滯后，就失去了

導(dǎo)航的意義。

?

【參考】謹(jǐn)慎注釋掉代碼。在上方詳細(xì)說明，而不是簡單地注釋掉。如果無用，則刪除。

說明：代碼被注釋掉有兩種可能性：1）后續(xù)會(huì)恢復(fù)此段代碼邏輯。2）永久不用。前者如果沒有備注信

息，難以知曉注釋動(dòng)機(jī)。后者建議直接刪掉（代碼倉庫已然保存了歷史代碼）。

?

【參考】對于注釋的要求：第一、能夠準(zhǔn)確反映設(shè)計(jì)思想和代碼邏輯；第二、能夠描述業(yè)務(wù)

含義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對于閱讀者

形同天書，注釋是給自己看的，即使隔很長時(shí)間，也能清晰理解當(dāng)時(shí)的思路；注釋也是給繼

任者看的，使其能夠快速接替自己的工作。

?

【參考】好的命名、代碼結(jié)構(gòu)是自解釋的，注釋力求精簡準(zhǔn)確、表達(dá)到位。避免出現(xiàn)注釋的

一個(gè)極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋是相當(dāng)大的負(fù)擔(dān)。

反例：

// put elephant into fridge

put(elephant, fridge);

方法名 put，加上兩個(gè)有意義的變量名 elephant 和 fridge，已經(jīng)說明了這是在干什么，語義清晰的代

碼不需要額外的注釋。

總結(jié)

以上是生活随笔為你收集整理的阿里Java编程规约（注释）提炼的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。