很多程式設計師在寫程式碼的時候往往都不注意程式碼的可讀性，讓別人在閱讀程式碼時花費更多的時間。其實，只要程式設計師在寫程式碼的時候，注意為程式碼加註釋，並以合理的格式為程式碼加註釋，這樣就方便別人檢視程式碼，也方便自己以後查看了。下面分享十個加註釋的技巧：

　　1. 逐層註釋

　　為每個程式碼塊添加註釋，並在每一層使用統一的註釋方法和風格。例如：

　　針對每個類：包括摘要資訊、作者資訊、以及最近修改日期等；

　　針對每個方法：包括用途、功能、引數和返回值等。

　　在團隊工作中，採用標準化的註釋尤為重要。當然，使用註釋規範和工具(例如C#裡的XML，Java裡的Javadoc)可以更好的推動註釋工作完成得更好。

　　2. 使用分段註釋

　　如果有多個程式碼塊，而每個程式碼塊完成一個單一任務，則在每個程式碼塊前新增一個註釋來向讀者說明這段程式碼的功能。例子如下：
提高程式碼可讀性的10個註釋技巧 伯樂線上 - 職場部落格

　　3. 在程式碼行後添加註釋

　　如果多行程式碼的每行都要添加註釋，則在每行程式碼後新增該行的註釋，這將很容易理解。例如：
提高程式碼可讀性的10個註釋技巧 伯樂線上 - 職場部落格

　　在分隔程式碼和註釋時，有的開發者使用tab鍵，而另一些則使用空格鍵。然而由於tab鍵在各編輯器和IDE工具之間的表現不一致，因此最好的方法還是使用空格鍵。

　　4. 不要侮辱讀者的智慧

　　避免以下顯而易見的註釋：寫這些無用的註釋會浪費你的時間，並將轉移讀者對該程式碼細節的理解。
提高程式碼可讀性的10個註釋技巧 伯樂線上 - 職場部落格

　　5. 禮貌點

　　避免粗魯的註釋，如：“注意，愚蠢的使用者才會輸入一個負數”或“剛修復的這個問題出於最初的無能開發者之手”。這樣的註釋能夠反映到它的作者是多麼的拙劣，你也永遠不知道誰將會閱讀這些註釋，可能是：你的老闆，客戶，或者是你剛才侮辱過的無能開發者。

　　6. 關注要點

　　不要寫過多的需要轉意且不易理解的註釋。避免ASCII藝術，搞笑，詩情畫意，hyperverbosity的註釋。簡而言之，保持註釋簡單直接。

　　7. 使用一致的註釋風格

　　一些人堅信註釋應該寫到能被非程式設計者理解的程度。而其他的人則認為註釋只要能被開發人員理解就行了。無論如何，Successful Strategies for Commenting Code已經規定和闡述了註釋的一致性和針對的讀者。就個人而言，我懷疑大部分非程式設計人員將會去閱讀程式碼，因此註釋應該是針對其他的開發者而言。

　　8. 使用特有的標籤

　　在一個團隊工作中工作時，為了便於與其它程式設計師溝通，應該採用一致的標籤集進行註釋。例如，在很多團隊中用TODO標籤表示該程式碼段還需要額外的工作。

　 註釋標籤切忌不要用於解釋程式碼，它只是引起注意或傳遞資訊。如果你使用這個技巧，記得追蹤並確認這些資訊所表示的是什麼。
提高程式碼可讀性的10個註釋技巧 伯樂線上 - 職場部落格

　　9. 在寫程式碼時添加註釋

　　在寫程式碼時就添加註釋，這時在你腦海裡的是清晰完整的思路。如果在程式碼最後再新增同樣註釋，它將多花費你一倍的時間。而“我沒有時間寫註釋”，“我很忙”和“專案已經延期了”這都是不願寫註釋而找的藉口。一些開發者覺得應該write comments before code，用於理清頭緒。例如：
提高程式碼可讀性的10個註釋技巧 伯樂線上 - 職場部落格

　　10. 為自己註釋程式碼

　　當註釋程式碼時，要考慮到不僅將來維護你程式碼的開發人員要看，而且你自己也可能要看。用Phil Haack大師的話來說就是：“一旦一行程式碼顯示螢幕上，你也就成了這段程式碼的維護者”。因此，對於我們寫得好(差)的註釋而言，我們將是第一個受益者(受害者)。


本文轉載自http://www.jobbole.com/entry.php