碼農的自我修養-對代碼註釋的理解(轉)

本文轉自:https://blog.csdn.net/ylforever/article/details/51171580

如何寫好代碼註釋是一個老話題，能夠說一千個程序員就有一千種不一樣的理解。下面是從我本身工做中所看到的，所聽到的；結合本身編碼的體會談一下本身的想法。

對代碼註釋的態度大體有三種誤區：

1. 註釋很重要，每一行代碼都要寫註釋。
2. 註釋無關緊要，爲了應付公司的編程規範，QA的審查，開始拷貝一些函數頭註釋，拷過去什麼都不改，連原做者名都不改，只爲知足代碼註釋率的要求。
3. 無需註釋，代碼即註釋。

第一種：新員工熱情很高，也頗有責任心，導師或者項目經理說要把註釋寫清楚啊。因而乎就屁顛屁顛的每一個變量，每一個分支，每行代碼都加上註釋。有時候寫了一句註釋生怕別人不理解，在加一句註釋來註釋前一句註釋。

寫了不少往後本身看起來都會發笑的註釋：

工做久了再來回過頭來看這些代碼註釋，猶如脫褲子放屁般淡定地陳述了一句很是正確的廢話。可是，誰沒有當年呢，誰沒有裝B的時候。回味一下也是一段很是有意思的記憶。

第二種：業務基本上混熟了，也能在項目中承擔一些核心的任務。以爲編碼就是體力活(有時確實也是)，只要功能實現了，代碼那怕寫得像一坨si也無所謂。拷貝拷貝就OK了。

這個階段每每開始考慮是走技術路線仍是走管理路線了，走技術路線是走業務分析路線仍是走架構設計路線。若是是有抱着前面描述想法的建議走業務分析路線或者管理路線，估計你對編碼沒多大興趣。我認識一我的，開發時寫的代碼在後續版本維護和增量開發過程當中沒法擴展，改着改着幾乎刪了重寫了；但這哥們業務研究的深刻，轉行作SE，如今轉入Marketing,也混得風生水起。因此說不想寫代碼，寫爛代碼並必定就是你的錯，可能你的興趣就不在這裏，找準本身的方向。

第三種：讀過兩本大師著做，不知道從哪聽到了「代碼即註釋，代碼即設計，代碼即文檔，代碼即XXX」。

總之，代碼註釋越少越是顯得本身牛X 。有時候維護的過程當中或者代碼檢視的過程當中看到這樣的代碼，大函數，圈複雜度老高，夾雜中式英語，全篇無註釋。看到有歧義的地方想問一下都不知道問誰。真想吼一聲：請註釋你那該死的代碼，你看它就是一坨si。

咱們倡導代碼自注釋，經過恰當的命名，合理的結構劃分讓代碼說話。可是不得不認可，代碼做爲人與計算機交互的語言，它的表達力，可理解性和人與人之間交流所使用的，通過千錘百煉的天然語言相比仍是比較弱的。恰當有效的註釋不只是值得鼓勵的並且是必須的。

經過實際經驗對比發現：真正的編程高手不光代碼寫的漂亮，註釋也寫得至關漂亮，不少時候寥寥幾筆註釋起到畫龍點睛的做用。而信仰並實踐着代碼即註釋的人大部分都是半桶水。能夠說看一個程序的代碼寫得怎麼樣，就看他的註釋寫得怎麼樣。

下面說說我對好的代碼註釋的理解：
一、註釋首先要告訴維護的人這段代碼是誰寫的。
不少代碼沒有函數頭註釋，不知道是不屑寫仍是怕寫。這不是一個好習慣，因爲代碼從開發到維護常常會換幾撥人，新手未必能理解你當時的意圖，這時能找人問一下是多麼重要。將心比心，若是讓你去維護一大塊代碼，看不懂又不知道問誰，估計也忍不住要破口大罵。

雖然現代的軟件開發都是有版本控制，比較版本樹能找到誰寫的代碼。可是，日積月累每一個文件的版本節點數百個，從裏面去找出某個函數，某處修改是誰寫的也是很可貴。

從我我的的理解，寫代碼不寫函數頭註釋要麼是太自信，要麼是太不自信。自信是以爲代碼寫得很好了，很容易理解；不自信是代碼寫得太爛了，怕被人揪出來罵。

二、註釋不是描述代碼作了什麼而是描述爲何這麼作。
如上面的舉例，註釋將代碼作的事情用語言再描述一遍，實際上是多此一舉。維護的人或者看代碼的人，最想知道的是爲何這麼作，是爲了解決什麼特殊問題嗎？有沒有什麼複雜的業務背景。至於怎麼作，看代碼就知道了。

固然，對於業務邏輯實在太複雜的部分。看代碼不能一下就看出個因此然來，經過一段文字說明，把關鍵點點出來，仍是頗有好處的。

三、註釋描述的內容應該和代碼是一致的。
這個就不說了，作過軟件開發的人都知道。修改代碼時未同步修改註釋，註釋成了誤導。錯誤的註釋比沒有註釋更糟糕。

參考這個。你說是該信代碼呢仍是信註釋。

四、函數頭註釋應該描述函數調用的前置條件和後置條件。
函數做爲供他人調用的一個接口，須要有它的使用說明書：在什麼場景下使用，使用後會產生什麼樣的後果，使用須知等。好比該函數返回的指針須要調用方主動釋放內存，若是調用方沒有釋放就會致使內存泄露。

五、取一個有意義的函數名，讓它自注釋。
函數是一個功能單元，作一件事情。函數名最好能定義爲動賓結構，最好能具體一點。好比校驗用戶名，校驗密碼能夠是CheckUserName,CheckPassword。若是是一個比較空泛的名稱就很差理解，像DoChecking之類的。

開發過程當中常常看到這樣的狀況：某個功能要處理A，B，C三件事，拆分紅三個函數，函數名就是DoA, DoB, DoC。只能說太隨意了，還能夠再斟酌一下，更具體一點。

六、取一個好的變量名，讓人不易誤用。
見過字符串變量就直接定義叫str，某個結構體量定義叫st。或者有時候函數中的臨時變量不知道定義什麼名稱，乾脆叫temp1, temp2,temp3…。抓狂

七、好的代碼註釋應該告訴後來人維護的思路。維護過程當中發現好的代碼註釋，註釋不只展現了做者清晰的思路，還將做者對後續可能出現的變化的思考也融入進來。做者在寫代碼時已經考慮了後續版本的需求哪裏可能會變化，變化後只要怎麼修改一下哪裏的代碼就能夠支持。這樣的代碼註釋看起來很舒心，做者是有思想的，也是負責任的。