編程規約
1. 註釋規約
- 【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範,使用/** 內容 */格式,不得使用 // xxx 方式。
說明: 在 IDE 編輯窗口中, Javadoc 方式會提示相關注釋,生成 Javadoc 可以正確輸出相應註釋; 在 IDE中,工程調用方法時,不進入方法即可懸浮提示方法、參數、返回值的意義,提高閱讀效率。
- 【強制】所有的抽象方法(包括接口中的方法) 必須要用 Javadoc 註釋、除了返回值、參數、異常說明外,還必須指出該方法做什麼事情,實現什麼功能。
說明: 對子類的實現要求,或者調用注意事項,請一併說明。
- 【強制】所有的類都必須添加創建者和創建日期。
- 【強制】方法內部單行註釋,在被註釋語句上方另起一行,使用//註釋。方法內部多行註釋使用/* */註釋,注意與代碼對齊。
- 【強制】所有的枚舉類型字段必須要有註釋,說明每個數據項的用途。
- 【推薦】與其“半吊子”英文來註釋,不如用中文註釋把問題說清楚。專有名詞與關鍵字保持英文原文即可。
反例: “TCP 連接超時”解釋成“傳輸控制協議連接超時”,理解反而費腦筋。
- 【推薦】代碼修改的同時,註釋也要進行相應的修改,尤其是參數、返回值、異常、核心邏輯等的修改。
說明: 代碼與註釋更新不同步,就像路網與導航軟件更新不同步一樣, 如果導航軟件嚴重滯後,就失去了導航的意義。
- 【參考】 謹慎註釋掉代碼。 在上方詳細說明,而不是簡單的註釋掉。 如果無用,則刪除。
說明: 代碼被註釋掉有兩種可能性: 1) 後續會恢復此段代碼邏輯。 2)
永久不用。前者如果沒有備註信息,難以知曉註釋動機。後者建議直接刪掉(代碼倉庫保存了歷史代碼) 。
- 【參考】對於註釋的要求:第一、能夠準確反應設計思想和代碼邏輯; 第二、能夠描述業務含義,使別的程序員能夠迅速瞭解到代碼背後的信息。
完全沒有註釋的大段代碼對於閱讀者形同天書,註釋是給自己看的,即使隔很長時間,也能清晰理解當時的思路;
註釋也是給繼任者看的,使其能夠快速接替自己的工作。
- 【參考】好的命名、代碼結構是自解釋的,註釋力求精簡準確、表達到位。避免出現註釋的一個極端:過多過濫的註釋,代碼的邏輯一旦修改,修改註釋是相當大的負擔。
反例: // put elephant into fridge put(elephant, fridge);
方法名 put,加上兩個有意義的變量名 elephant 和 fridge,已經說明了這是在幹什麼,語義清晰的代碼不需要額外的註釋。
- 【參考】特殊註釋標記,請註明標記人與標記時間。注意及時處理這些標記,通過標記掃描,經常清理此類標記。線上故障有時候就是來源於這些標記處的代碼。
1) 待辦事宜(TODO) :(標記人,標記時間, [預計處理時間]) 表示需要實現,但目前還未實現的功能。這實際上是一個 Javadoc
的標籤,目前的 Javadoc還沒有實現,但已經被廣泛使用。只能應用於類,接口和方法(因爲它是一個 Javadoc 標籤) 。 2)
錯誤,不能工作(FIXME) :(標記人,標記時間, [預計處理時間]) 在註釋中用 FIXME
標記某代碼是錯誤的,而且不能工作,需要及時糾正的情況。