Like Share Discussion Bookmark Smile

J.J. Huang   2020-05-06   Java   瀏覽次數:

《阿里Java開發手冊》 | 編程規約 - 註解規約

【強制】類、類屬性、類方法的註解必須使用 Javadoc 規範,使用/**內容*/格式,不得使用 // xxx 方式。
說明:在 IDE 編輯窗口中,Javadoc 方式會提示相關註解,生成 Javadoc 可以正確輸出相應註解;在 IDE 中,工程調用方法時,不進入方法即可懸浮提示方法、參數、返回值的意義,提高閱讀效率。


【強制】所有的抽象方法(包括接口中的方法)必須要用 Javadoc 註解、除了返回值、參數、異常說明外,還必須指出該方法做什麼事情,實作什麼功能。
說明:對子類的實作要求,或者調用注意事項,請一併說明。


【強制】所有的類都必須添加建立者和建立日期。
說明:在設置模板時,注意 IDEA 的 @author 為`${USER}`,而 eclipse 的 @author 為`${user}`,大小寫有區別,而日期的設置統一為 yyyy/MM/dd 的格式。
正例:

1
2
3
4
/**
* @author yangguanbao
* @date 2016/10/31
*/

【強制】方法內部單行註解,在被註解語句上方另起一行,使用//註解。方法內部多行註解使用/* */註解,注意與程式碼對齊。


【強制】所有的枚舉類型欄位必須要有註解,說明每個資料項的用途。


【推薦】與其“半吊子”英文來註解,不如用中文註解把問題說清楚。專有名詞與關鍵字保持英文原文即可。
反例:“TCP 連接超時”解釋成“傳輸控制協議連接超時”,理解反而費腦筋。


【推薦】程式碼修改的同時,註解也要進行相應的修改,尤其是參數、返回值、異常、核心邏輯等的修改。
說明:程式碼與註解更新不同步,就像路網與導航軟體更新不同步一樣,如果導航軟體嚴重滯後,就失去了導航的意義。


【推薦】在類中刪除未使用的任何欄位和方法;在方法中刪除未使用的任何參數聲明與內部變數。


【參考】謹慎註解掉程式碼。在上方詳細說明,而不是簡單地註解掉。如果無用,則刪除。
說明:程式碼被註解掉有兩種可能性:

  • 後續會恢復此段程式碼邏輯。
  • 永久不用。前者如果沒有備註訊息,難以知曉註解動機。後者建議直接刪掉即可,假如需要查閱歷史程式碼,登錄程式碼倉庫即可。

【參考】對於註解的要求:第一、能夠準確反映設計思想和程式碼邏輯;第二、能夠描述業務含義,使別的工程師能夠迅速了解到程式碼背後的訊息。完全沒有註解的大段程式碼對於閱讀者形同天書,註解是給自己看的,即使隔很長時間,也能清晰理解當時的思路;註解也是給繼任者看的,使其能夠快速接替自己的工作。


【參考】好的命名、程式碼結構是自解釋的,註解力求精簡準確、表達到位。避免出現註解的一 個極端:過多過濫的註解,程式碼的邏輯一旦修改,修改註解是相當大的負擔。
反例:

1
2
// put elephant into fridge
put(elephant, fridge);

方法名 put,加上兩個有意義的變數名 elephant 和 fridge,已經說明了這是在幹什麼,語義清晰的程式碼不
需要額外的註解。


【參考】特殊註解標記,請註明標記人與標記時間。注意及時處理這些標記,通過標記掃描, 經常清理此類標記。線上故障有時候就是來源於這些標記處的程式碼。

  • 待辦事宜(TODO):(標記人,標記時間,[預計處理時間]) 表示需要實作,但目前還未實作的功能。這實際上是一個 Javadoc 的標籤,目前的 Javadoc 還沒有實作,但已經被廣泛使用。只能應用於類,接口和方法(因為它是一個 Javadoc 標籤)。
  • 錯誤,不能工作(FIXME):(標記人,標記時間,[預計處理時間])
    在註解中用 FIXME 標記某程式碼是錯誤的,而且不能工作,需要及時糾正的情況。

心得

看完這篇「註解規約」後,非常有感觸,當在維護別人撰寫的程式碼的時候,經常就是當天書在看,什麼註解什麼說明都沒有;最可怕的莫過於沒在使用的程式碼沒有做刪除;還有註解的說明跟程式碼完全對不上或是邏輯相反⋯。

只能說在維護註解是個成本,但是這些註解絕對是在日後維護或是功能再次開發會有很大幫助的。

結語

文章越看越多,技術越學越多,就會發現自己的不足;技術學到後面都會想要將基礎再重新在打得更加扎實。

以前在開發覺得理所當然的事情,例如:命名規則、命名規範,照著別人怎麼說就怎麼做的想法,並沒有好好去想為什麼要這樣設計和規範。
於是乎同事們推薦《阿里巴巴Java開發手冊》來做閱讀,書中提到種種規範《正確範例》、《錯誤範例》還有解釋定義說明;我相信在閱讀完這一系列後,一定會更加扎實且實在。

如對此書有興趣,建議去購買官方認證的書籍,給予官方支持。

註:如有侵權,通知即刪。


註:以上參考了
Alibaba-Java-Coding-Guidelines Github
Alibaba-Java-Coding-Guidelines English Version