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