幾乎所有的軟件工程師，都追求寫(xiě)出漂亮的代碼，但是在學(xué)如何寫(xiě)好代碼的同時(shí)，卻很少有人關(guān)注寫(xiě)好代碼注釋的重要性，有的工程師從來(lái)都不寫(xiě)注釋?zhuān)J(rèn)為 talk is cheap，也有的工程師寫(xiě)出的注釋會(huì)讓原本已經(jīng)難以維護(hù)的代碼，變的更加難以維護(hù)。好的注釋往往能起到畫(huà)龍點(diǎn)睛的作用，提高我們維護(hù)代碼的效率。對(duì)于如何寫(xiě)好注釋?zhuān)铱偨Y(jié)了以下幾點(diǎn)：
1. 不寫(xiě)無(wú)意義的注釋
// 從服務(wù)端請(qǐng)求數(shù)據(jù)
getDataFromServer();
無(wú)意義的注釋就像廢話(huà)一樣多余，明明代碼已經(jīng)很清楚的表達(dá)“從服務(wù)端請(qǐng)求數(shù)據(jù)”了，卻又添加了一行跟代碼表達(dá)的意義一模一樣的注釋。不僅沒(méi)給我們帶來(lái)任何更多的信息，而且還隨著需求的不斷變化，可能會(huì)演變出下面這個(gè)問(wèn)題。
2. 不要修改了代碼邏輯，卻不修改注釋
// 從服務(wù)端請(qǐng)求數(shù)據(jù)
getDataFromCache();
當(dāng)需求改變時(shí)，我們修改了代碼邏輯，卻不隨之修改代碼注釋。就像上面代碼里寫(xiě)的，明顯注釋與代碼表達(dá)的意義不一致。這樣的注釋會(huì)讓維護(hù)者迷惑，因?yàn)榭赡軙?huì)真的認(rèn)為 getDataFromCache() 的方法里封裝了從服務(wù)器請(qǐng)求數(shù)據(jù)的能力。但是檢查了方法內(nèi)的邏輯可能才發(fā)現(xiàn)事實(shí)并不是這樣。這樣的注釋?zhuān)瑹o(wú)形之中增加了我們的維護(hù)成本。
3. 不要寫(xiě)只有 TODO 或者 FIX 的注釋
// TODO
getDataFromCache();
TODO 與 FIX 是很好用的代碼注釋標(biāo)簽，不僅能幫助我們快速的統(tǒng)計(jì)到 TODO 與 FIX，還可以指導(dǎo)我們后續(xù)需要繼續(xù)跟進(jìn)的事項(xiàng)，但是我維護(hù)過(guò)的不少代碼里，有時(shí)只有一個(gè)孤零零的 TODO 作為注釋?zhuān)@會(huì)讓我非常難受，因?yàn)楦緹o(wú)法清楚這里的代碼還有哪些未完成的功能，這個(gè)時(shí)候通常只能祈禱寫(xiě)這個(gè) TODO 的同學(xué)還未離職，但你找到他詢(xún)問(wèn)的時(shí)候，很可能連他自己都已經(jīng)忘記為什么這里有一個(gè) TODO 的注釋了。所以你甚至可以不寫(xiě)注釋?zhuān)f(wàn)別只寫(xiě)一個(gè) TODO。
4. 在合適的項(xiàng)目里寫(xiě)英文注釋
曾經(jīng)有段時(shí)間，我認(rèn)為英文代碼似乎只有配上英文注釋才顯得自然優(yōu)雅。而且優(yōu)秀的開(kāi)源項(xiàng)目與系統(tǒng)源碼也都是這樣做的，因此我也開(kāi)始只寫(xiě)英文注釋。但是直到有一天，我看到團(tuán)隊(duì)里的新手工程師在理解代碼邏輯已經(jīng)很困難的情況下，還要理解語(yǔ)法可能都不對(duì)的英文注釋時(shí)，我重新思考了這個(gè)問(wèn)題，并有了新的理解：如果我們是在做個(gè)人項(xiàng)目，開(kāi)源項(xiàng)目或者團(tuán)隊(duì)中有國(guó)外開(kāi)發(fā)者，那我們確實(shí)應(yīng)該統(tǒng)一使用英文注釋。但是如果我們是在一家國(guó)內(nèi)公司做商業(yè)項(xiàng)目，當(dāng)我們無(wú)法確定團(tuán)隊(duì)里的每一個(gè)人都能準(zhǔn)確的理解英文注釋時(shí)。為了項(xiàng)目的開(kāi)發(fā)效率與維護(hù)成本考慮，我建議使用中文注釋。
寫(xiě)好注釋一點(diǎn)也不難，注意好前面幾點(diǎn)，再克服一點(diǎn)點(diǎn)惰性，連不會(huì)寫(xiě)代碼的人都能寫(xiě)好注釋了。好好寫(xiě)注釋?zhuān)愕囊恍凶⑨尶赡軙?huì)給另一位工程師節(jié)省一下午的時(shí)間。
