阿里巴巴Java开发编码规范—注释规约
目錄
強(qiáng)制
推薦
參考
強(qiáng)制
1.類、類屬性、類方法的注釋必須使用javadoc規(guī)范,使用/**內(nèi)容*/格式,不得使用//xxx方式。
2.所有的抽象方法(包括接口中的方法)必須使用javadoc注釋,除了返回值、參數(shù)、異常說明外,還必須指出該方法做什么事情,實(shí)現(xiàn)什么功能。
3.所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。
4.方法內(nèi)部單行注釋在被注釋語(yǔ)句上另起一行,使用//注釋,方法內(nèi)部多行注釋使用/* */注釋,注意與代碼對(duì)齊。
5.所有的枚舉類型必須要有注釋,說明每個(gè)數(shù)據(jù)項(xiàng)的用途。
推薦
1.與其“半吊子”英文來(lái)注釋,不如用中文注釋把問題說清楚。專有名詞和關(guān)鍵字保持英文原文即可。
2.代碼修改的同時(shí),注釋也要進(jìn)行相應(yīng)的修改,尤其是參數(shù)、返回值、異常、核心邏輯等的修改。
參考
1.謹(jǐn)慎注釋掉代碼。在上面詳細(xì)說明,而不是簡(jiǎn)單地注釋掉。如果無(wú)用則刪除。注釋刪掉會(huì)用兩種可能性:1.后續(xù)會(huì)恢復(fù)此段代碼邏輯。2.永久不用。前者如果沒有備注信息難以知曉其動(dòng)機(jī),后者建議直接刪掉。
2.對(duì)于注釋的要求:能夠準(zhǔn)確反映設(shè)計(jì)思路和代碼邏輯;能夠描述業(yè)務(wù)含義,使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對(duì)于閱讀者如同天書。
3.好的命名、代碼結(jié)構(gòu)是自解釋的,注釋力求精簡(jiǎn)準(zhǔn)確,表達(dá)到位。避免出現(xiàn)注釋的一個(gè)極端:過多的注釋,代碼邏輯一旦修改,注釋的修改是相當(dāng)大的負(fù)擔(dān)。
4.特殊注釋標(biāo)記,要注明標(biāo)記人和標(biāo)記時(shí)間。并且要及時(shí)處理這些標(biāo)記,通過標(biāo)記掃描,經(jīng)常清理此類標(biāo)記。
- ?? ?代辦事宜(TODO):表明需要實(shí)現(xiàn)但目前還未實(shí)現(xiàn)的功能。
- ?? ?錯(cuò)誤(FIXME) ? :表明某代碼是錯(cuò)誤的,而且不能工作,需要及時(shí)糾正。
總結(jié)
以上是生活随笔為你收集整理的阿里巴巴Java开发编码规范—注释规约的全部?jī)?nèi)容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 高服从编纂器 VIM-操作篇(1)
- 下一篇: 接视频Java 数据库