注釋毫無疑問是讓別人以最快速度了解你代碼的最快途徑，但寫注釋的目的絕不僅僅是"解釋代碼做了什么"，更重要的盡量幫助代碼閱讀者對代碼了解的和作者一樣多。
當你寫代碼時，你腦海里會有很多有價值的信息，但當其他人讀你代碼時，這些信息已經丟失，他們所見到的只是眼前代碼。
如果IDE提供注釋格式，則盡量使用IDE提供的格式，否則使用"http://"來注釋。類、屬性和方法的注釋在Visual Studio中都使用輸入"http:///"自動生成的格式。
/// <summary>
/// 類說明
/// </summary>
public class BinaryTree
/// <summary>
/// 屬性說明
/// </summary>
public int NodesCount { get; PRivate set; }
/// <summary>
/// 方法說明
/// </summary>
/// <param name="parentNode">參數說明</param>
/// <returns>返回值說明</returns>
public int ComputeChildNodesCount(BinaryNode parentNode)
//單行注釋
/*多行注釋1
多行注釋2
多行注釋3*/
/***************************************************
* 代碼塊注釋1
*代碼塊注釋2
*......
*代碼塊注釋10
*代碼塊注釋11
***************************************************/
這里約定下以后團隊常用幾種注釋標識及含義：
//TODO: 我還沒有處理的事情
//FIXME: 已知的問題
//HACK: 對一個問題不得不采用比較粗糙的解決方案
//XXX: 危險！這里有重要的問題
請團隊成員自行在Visual Studio中配置FIXME和XXX為高優先級的Comments.
Steps: Tools->Options->Environment->Task List->Tokens->Add->OK
配置完成后，我們就能在Task List（Ctrl+w,t）窗口中的Comments選項中看到代碼中存在的任務了。
a. 對于需要讓調用者知道的信息，使用“///”注釋，以便讓調用者能在調用時看到。
b. 對于代碼內部實現細節，需要維護者知道的注釋，使用“//”。減少調用者閱讀時間。
閱讀注釋會占用閱讀真實代碼的時間，并且每條注釋都會占用屏幕上的空間。所以我們約定所加的注釋必須是有意義的注釋，否則不要浪費時間和空間。
區別要不要寫注釋的核心思想就是:不要為那些能快速從代碼本身就推斷的事實寫注釋。
有些人可能以前的公司對于注釋要求很高，如"何時寫注釋"章節中的要求。所以很多人為了寫注釋而注釋。
再沒有特殊要求的情況下我們要禁止寫下面這種沒有意義的注釋。
/// <summary>
/// The class definition for Account
/// </summary>
publicclassBinaryTree
{
/// <summary>
/// Total counts of the nodes
/// </summary>
publicint NodesCount { get; privateset; }
/// <summary>
/// All the nodes in the tree
/// </summary>
publicList<BinaryNode> Nodes { get; set; }
/// <summary>
/// Insert a node to the tree
/// </summary>
/// <param name="node">the node you want insert into the tree</param>
publicvoid InsertNode(BinaryNode node)
寫注釋常見的動機之一就是試圖來使糟糕的代碼能讓別人看懂。對于這種"拐杖式注釋"，我們不需要，我們要做的是把代碼改的能夠更具有"自我說明性"。
記?。?好代碼>壞代碼+好注釋"
如下面這段函數的注釋
//Enforce limits on the reply as stated in the request
//such as the number of items returned, or total byte size,etc.
publicvoid CleanReply(Request request,Reply reply)
既然知道這個函數名會讓人很難讀懂，那么為什么不直接改好名字呢？這樣所有調用這個函數的地方都能很快速知道這個函數的作用，不用再跟進來看函數的作用。
publicvoid EnforceLimitsFromRequestOnReply(Request request,Reply reply)
有人喜歡在每次編輯代碼時，都在模塊開始處加一條注釋。這類注釋就像是一種記錄每次修改的日志。在很久以前這種記錄對于維護還有意義。但是對于現在的源碼控制來說，這些記錄完全是冗余的，需要完全廢除。
/***************************************************
* July-29-2014:Fix Bug-12345: Add new method to calculate nodes count
*July-20-2014:Fix Bug-11111: Add Insert new node method
*......
*July-20-2014:Task-00001: Create BinaryTree class
***************************************************/
//Added By XXXX
有人認為這種注釋有助于不了解這段代碼含意的人和他討論。事實上確是這條注釋放在那一年復一年，后來的代碼和原作者寫的源碼越來越不一樣，和XXXX也越來越沒關系。
重申一下，TFS里都能看到這類信息，不要加在代碼里。
//AddNodePlace1
//AddNodePlace2
有人喜歡在代碼注釋里加入位置標識以方便他查找代碼的位置。
現在的IDE都集成了這些功能，如VS中可以使用Bookmark(Ctrl+b,t)。
不要將這類注釋加到代碼中。
直接把代碼注釋掉是非常令人討厭的做法。
其他人不敢刪掉這些代碼。他們會想代碼依然在這一定是有原因的，而且這段代碼很重要，不能刪除。而且每個閱讀代碼的人都會去看一下這些被注釋掉的代碼中是否有他們需要注意的信息。
這些注釋掉的代碼會堆積在一起，散發著腐爛的惡臭。
你應該在代碼中加入你對代碼這段代碼有價值的見解注釋。
如：//出乎意料的是，對于這些數據用二叉樹比哈希表要快40%
//哈希運算的代價比左右比要大的多
這段注釋會告訴讀者一些重要的性能信息，防止他們做無謂的優化。
代碼始終在演進，并且在代碼中肯定會有不足。
要把這些不足記錄下來以便后來人完善。
如當代碼需要改進時：
//TODO:嘗試優化算法
如當代碼沒有完成時：
//TODO:處理JPG以外的圖片格式
你應該隨時把代碼將來該如何改動的想法用注釋的方式記錄下來。這種注釋給讀者帶來對代碼質量和當前狀態的寶貴見解，甚至會給他們指出如何改進代碼的方向。
當別人讀你的代碼的時候，有些部分可能讓他們有這樣的疑問："為什么要這樣寫？"你的工作就是要給這些部分加上注釋。
如：
// 因為Connection的創建很耗費資源和時間，而且需要多線程訪問，
// 所以使用多線程單例模式
publicstaticConnection Instance
{
get
{
if(_instance==null)
{
lock (_lock)
{
if (_instance ==null)
{
_instance =newConnection();
}
}
}
return _instance;
}
}
當為一個函數或者類寫注釋時，可以這樣的問自己:"這段代碼有什么出人意料的地方嗎？會不會被無用？"?；旧险f就是你需要未雨綢繆，預料到別人使用你代碼時可能遇到的問題。如：
//XXX: 因為調用外部郵件服務器發送郵件，所以耗時較長，請使用異步方法調用以防止UI卡死。
publicvoid SendEmail(string to, string subject, string body)
對于代碼塊的總結性注釋可以使讀者在深入細節之前就能得到該代碼塊的主旨，甚至有時候都可以直接跳過該代碼塊，從而可以快速準確的把握代碼。
如讀者看到：//下面代碼使用了二分查找算法來快速的根據用戶Id找到相應用戶
那么他就可以快速理解下面代碼的邏輯，否則自己看二分查找還是要用些時間的。
新聞熱點
疑難解答
