什么也比不上放置良好的注釋來得有用,什么也比不上亂七八糟的注釋更能搞亂一個模塊.沒有什么能比陳舊,提供錯誤信息的注釋更有破壞性.如果編程語言能有足夠的表達力,我們便最好不要寫注釋,因為沒有多少程序員在維護代碼時愿意花大量的時間和精力修改注釋.久而久之,原有的注釋便會失去代碼所表達的含義.
如果發(fā)現(xiàn)自己需要寫注釋表達含義,想想是否可以用代碼代替表達.不準確的注釋比沒有注釋壞的多.只有代碼能忠實地告訴讀者它做了什么事情.所以,唯一真正的好注釋就是不去寫注釋,不斷美化代碼來表達含義.
好注釋
法律信息
有些公司代碼規(guī)范要求編寫與法律有關(guān)的注釋.例如,版權(quán)和著作權(quán)申明必須放在某些文件的開頭注釋.
提供信息的注釋
用注釋提供基本信息,比如:方法的前提信息,后續(xù)處理注意事項等等.這類注釋有時管用,但,如果可以用函數(shù)名代替,盡量用代碼表達含義.
對意圖的理解
在注釋里寫明代碼這么處理的意圖.
闡釋
注釋陳某些難懂的參數(shù)或返回值的意義翻譯為可讀形式,也許會有用.通常,更好的方法是盡量讓參數(shù)或返回值自身就足夠清楚.但,如果返回值是某個標準庫的一部分或者是不能修改的代碼,幫助闡述其含義的注釋就會有用.但,添加的注釋一定要保證其正確性.
警示
有時,警告其他程序員會出現(xiàn)某種后果的注釋也是有用的.特別是強調(diào)某種不合理的操作.
壞注釋
喃喃自語
很多注釋似乎寫出來是開發(fā)者提醒自己應(yīng)該要怎么做之類的,其實這些注釋是無謂之舉.
多余的注釋
這些注釋沒有說明代碼的意義,也沒有給出代碼的意義和邏輯,甚至讀它比讀代碼更耗精力和時間.
循規(guī)蹈矩式注釋
所謂每個函數(shù)都要有注釋,每個類都應(yīng)該有一致性的注釋,這完全是不對的.代碼本身具有解釋性還要注釋干啥?
括號后面的注釋
很多注釋需要添加在一個循環(huán)嵌套另一個循環(huán)的地方,不然過多的嵌套會亂花我們的眼睛.或許我們可以嘗試重構(gòu)代碼,減少循環(huán)嵌套了.而不是一味添加注釋.
歸屬和署名
很多代碼文件擁有作者署名,似乎這樣可以說明這個文件某個作者最熟悉,其他人碰到問題可以和他討論.但事實情況是代碼修改了一遍又一遍,最后的代碼連作者本人也不認識了.
注釋掉的代碼
很多代碼被注釋,它就永遠在那邊靜靜呆著了.注釋掉的作者不刪掉,其他人也不敢刪,擔(dān)心是否還有某種用途.所以,注釋掉的代碼比真正的注釋還要難對付,該刪時還是及時刪掉吧.
不明顯的聯(lián)系
注釋和代碼之間的聯(lián)系顯而易見,很多注釋放置的位置讓人摸不著頭腦,找不到對應(yīng)的代碼塊.這需要注意.
注
這里僅僅給出了部分注釋的好壞情況,如果有疏忽請留言提醒.謝謝!
