1.【強(qiáng)制】類、類屬性、類方法的注釋必須使用 Javadoc 規(guī)范嘹黔，使用 /** 內(nèi)容 */ 格式，不得使用 // xxx 方式莫瞬。
說明：在 IDE 編輯窗口中儡蔓，Javadoc 方式會(huì)提示相關(guān)注釋，生成 Javadoc 可以正確輸出相應(yīng)注釋疼邀；在 IDE 中喂江，工程調(diào)用方法時(shí)，不進(jìn)入方法即可懸浮提示方法旁振、參數(shù)获询、返回值的意義，提高閱讀效率拐袜。
2.【強(qiáng)制】所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋吉嚣、除了返回值、參數(shù)異常說明外蹬铺，還必須指出該方法做什么事情尝哆，實(shí)現(xiàn)什么功能。
說明：對(duì)子類的實(shí)現(xiàn)要求丛塌，或者調(diào)用注意事項(xiàng)较解，請(qǐng)一并說明畜疾。
3.【強(qiáng)制】所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。
說明：在設(shè)置模板時(shí)印衔，注意 IDEA 的 @author 為${USER}啡捶，而 eclipse 的@author 為${user}，大小寫有區(qū)別奸焙，而日期
的設(shè)置統(tǒng)一為 yyyy/MM/dd 的格式瞎暑。
正例：
/**
*
* @author yangguanbao
* @date 2021/11/26
*
**/
4.【強(qiáng)制】方法內(nèi)部單行注釋，在被注釋語句上方另起一行与帆，使用 // 注釋了赌。方法內(nèi)部多行注釋使用 /* */
注釋，注意與代碼對(duì)齊玄糟。
5.【強(qiáng)制】所有的枚舉類型字段必須要有注釋勿她，說明每個(gè)數(shù)據(jù)項(xiàng)的用途。
6.【推薦】與其用半吊子英文來注釋阵翎，不如用中文注釋說清楚逢并。專有名詞與關(guān)鍵字保持英文原文即可。
反例：“TCP 連接超時(shí)”解釋成“傳輸控制協(xié)議連接超時(shí)”郭卫，理解反而費(fèi)腦筋砍聊。
7.【推薦】代碼修改的同時(shí)，注釋也要進(jìn)行相應(yīng)的修改贰军，尤其是參數(shù)玻蝌、返回值、異常词疼、核心邏輯等俯树。
說明：代碼與注釋更新不同步，就像公路網(wǎng)與導(dǎo)航軟件更新不同步一樣寒跳，如果導(dǎo)航軟件嚴(yán)重滯后聘萨，就失去了導(dǎo)航的意義竹椒。
8.【推薦】在類中刪除未使用的任何字段和方法童太、內(nèi)部類；在方法中刪除未使用的參數(shù)聲明與內(nèi)部變量胸完。
9.【參考】謹(jǐn)慎注釋掉代碼书释。在上方詳細(xì)說明，而不是簡單地注釋掉赊窥。如果無用爆惧，則刪除。
說明：代碼被注釋掉有兩種可能性：1）后續(xù)會(huì)恢復(fù)此段代碼邏輯锨能。2）永久不用扯再。前者如果沒有備注信息芍耘，難以知曉注釋動(dòng)機(jī)。后者建議直接刪掉即可熄阻，假如需要查閱歷史代碼斋竞，登錄代碼倉庫即可。
10.【參考】對(duì)于注釋的要求：第一秃殉、能夠準(zhǔn)確反映設(shè)計(jì)思想和代碼邏輯坝初；第二、能夠描述業(yè)務(wù)含義钾军，使別的程序員能夠迅速了解到代碼背后的信息鳄袍。完全沒有注釋的大段代碼對(duì)于閱讀者形同天書，注釋是給自己看的吏恭，即使隔很長時(shí)間拗小，也能清晰理解當(dāng)時(shí)的思路；注釋也是給繼任者看的樱哼，使其能夠快速接替自己的工作十籍。
11.【參考】好的命名、代碼結(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)說明了這是在干什么，語義清晰的代碼不需要額外的注釋漾抬。
12.【參考】特殊注釋標(biāo)記宿亡，請(qǐng)注明標(biāo)記人與標(biāo)記時(shí)間。注意及時(shí)處理這些標(biāo)記纳令，通過標(biāo)記掃描挽荠，經(jīng)常清理此類標(biāo)記。線上故障有時(shí)候就是來源于這些標(biāo)記處的代碼平绩。
1）待辦事宜（TODO）：（標(biāo)記人圈匆，標(biāo)記時(shí)間，[預(yù)計(jì)處理時(shí)間]）表示需要實(shí)現(xiàn)捏雌，但目前還未實(shí)現(xiàn)的功能跃赚。這實(shí)際上是一個(gè) Javadoc 的標(biāo)簽，目前的 Javadoc 還沒有實(shí)現(xiàn)性湿，但已經(jīng)被廣泛使用纬傲。只能應(yīng)用于類满败，接口和方法（因?yàn)樗且粋€(gè)Javadoc 標(biāo)簽）。
2）錯(cuò)誤叹括，不能工作（FIXME）：（標(biāo)記人葫录，標(biāo)記時(shí)間，[預(yù)計(jì)處理時(shí)間]）在注釋中用 FIXME 標(biāo)記某代碼是錯(cuò)誤的领猾，而且不能工作米同，需要及時(shí)糾正的情況。
參考
- 2022 Java開發(fā)手冊(cè)(黃山版).pdf
- 白話阿里巴巴Java開發(fā)手冊(cè)（安全規(guī)約） - 李艷鵬 - 簡書(http://www.reibang.com/p/9528c4ea1504)
