自己總結(jié)的C#編碼規(guī)范--4.注釋篇

• 注釋

注釋毫無疑問是讓別人以最快速度了解你代碼的最快途徑，但寫注釋的目的絕不僅僅是"解釋代碼做了什么"，更重要的盡量幫助代碼閱讀者對(duì)代碼了解的和作者一樣多。

當(dāng)你寫代碼時(shí)，你腦海里會(huì)有很多有價(jià)值的信息，但當(dāng)其他人讀你代碼時(shí)，這些信息已經(jīng)丟失，他們所見到的只是眼前代碼。

• 注釋約定

如果IDE提供注釋格式，則盡量使用IDE提供的格式，否則使用"http://"來注釋。類、屬性和方法的注釋在Visual Studio中都使用輸入"http:///"自動(dòng)生成的格式。

• 類注釋約定

/// <summary>

/// 類說明

/// </summary>

public class BinaryTree

• 類屬性注釋約定

/// <summary>

/// 屬性說明

/// </summary>

public int NodesCount { get; PRivate set; }

• 方法注釋約定

/// <summary>

/// 方法說明

/// </summary>

/// <param name="parentNode">參數(shù)說明</param>

/// <returns>返回值說明</returns>

public int ComputeChildNodesCount(BinaryNode parentNode)

• 代碼間注釋約定

1. 單行注釋，注釋行數(shù)<3行時(shí)使用

   //單行注釋

2. 多行注釋，2<注釋行數(shù)<=10時(shí)使用

   /*多行注釋1

   多行注釋2

   多行注釋3*/

3. 注釋塊，10<注釋行數(shù)時(shí)使用，用50個(gè)*

   /***************************************************

   * 代碼塊注釋1

   *代碼塊注釋2

   *......

   *代碼塊注釋10

   *代碼塊注釋11

   ***************************************************/

• 何時(shí)寫注釋的約定

1. 以下三種情況我們需要在所有的類、類屬性和方法都必須按照上述格式編寫注釋
   1. 客戶方對(duì)代碼注釋重視程度較高
   2. 我們需要提供代碼注釋自動(dòng)生成的API文檔。

   

   1. 目前編寫的是公共核心模塊
2. 如果客戶方?jīng)]有對(duì)注釋特殊要求，那么按照下文中討論的只在需要的地方加注釋。不要加無謂的注釋。

• 常用注釋標(biāo)識(shí)的約定

這里約定下以后團(tuán)隊(duì)常用幾種注釋標(biāo)識(shí)及含義：

//TODO: 我還沒有處理的事情

//FIXME: 已知的問題

//HACK: 對(duì)一個(gè)問題不得不采用比較粗糙的解決方案

//XXX: 危險(xiǎn)！這里有重要的問題

請(qǐng)團(tuán)隊(duì)成員自行在Visual Studio中配置FIXME和XXX為高優(yōu)先級(jí)的Comments.

Steps: Tools->Options->Environment->Task List->Tokens->Add->OK

配置完成后，我們就能在Task List（Ctrl+w,t）窗口中的Comments選項(xiàng)中看到代碼中存在的任務(wù)了。

• 關(guān)于何時(shí)使用“///”和“//”的約定

a. 對(duì)于需要讓調(diào)用者知道的信息，使用“///”注釋，以便讓調(diào)用者能在調(diào)用時(shí)看到。

b. 對(duì)于代碼內(nèi)部實(shí)現(xiàn)細(xì)節(jié)，需要維護(hù)者知道的注釋，使用“//”。減少調(diào)用者閱讀時(shí)間。

• 不需要的注釋

閱讀注釋會(huì)占用閱讀真實(shí)代碼的時(shí)間，并且每條注釋都會(huì)占用屏幕上的空間。所以我們約定所加的注釋必須是有意義的注釋，否則不要浪費(fèi)時(shí)間和空間。

區(qū)別要不要寫注釋的核心思想就是:不要為那些能快速從代碼本身就推斷的事實(shí)寫注釋。

• 不要為了注釋而注釋

有些人可能以前的公司對(duì)于注釋要求很高，如"何時(shí)寫注釋"章節(jié)中的要求。所以很多人為了寫注釋而注釋。

再?zèng)]有特殊要求的情況下我們要禁止寫下面這種沒有意義的注釋。

/// <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)

• 不要用注釋來粉飾糟糕的代碼

寫注釋常見的動(dòng)機(jī)之一就是試圖來使糟糕的代碼能讓別人看懂。對(duì)于這種"拐杖式注釋"，我們不需要，我們要做的是把代碼改的能夠更具有"自我說明性"。

記住："好代碼>壞代碼+好注釋"

如下面這段函數(shù)的注釋

//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)

既然知道這個(gè)函數(shù)名會(huì)讓人很難讀懂，那么為什么不直接改好名字呢？這樣所有調(diào)用這個(gè)函數(shù)的地方都能很快速知道這個(gè)函數(shù)的作用，不用再跟進(jìn)來看函數(shù)的作用。

publicvoid EnforceLimitsFromRequestOnReply(Request request,Reply reply)

• 日志式注釋

有人喜歡在每次編輯代碼時(shí)，都在模塊開始處加一條注釋。這類注釋就像是一種記錄每次修改的日志。在很久以前這種記錄對(duì)于維護(hù)還有意義。但是對(duì)于現(xiàn)在的源碼控制來說，這些記錄完全是冗余的，需要完全廢除。

/***************************************************

* 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

***************************************************/

• 個(gè)人簽名

//Added By XXXX

有人認(rèn)為這種注釋有助于不了解這段代碼含意的人和他討論。事實(shí)上確是這條注釋放在那一年復(fù)一年，后來的代碼和原作者寫的源碼越來越不一樣，和XXXX也越來越?jīng)]關(guān)系。

重申一下，TFS里都能看到這類信息，不要加在代碼里。

• 位置標(biāo)識(shí)

//AddNodePlace1

//AddNodePlace2

有人喜歡在代碼注釋里加入位置標(biāo)識(shí)以方便他查找代碼的位置。

現(xiàn)在的IDE都集成了這些功能，如VS中可以使用Bookmark(Ctrl+b,t)。

不要將這類注釋加到代碼中。

• 注釋掉的代碼

直接把代碼注釋掉是非常令人討厭的做法。

其他人不敢刪掉這些代碼。他們會(huì)想代碼依然在這一定是有原因的，而且這段代碼很重要，不能刪除。而且每個(gè)閱讀代碼的人都會(huì)去看一下這些被注釋掉的代碼中是否有他們需要注意的信息。

這些注釋掉的代碼會(huì)堆積在一起，散發(fā)著腐爛的惡臭。

• 需要的注釋

• 記錄你對(duì)代碼有價(jià)值的見解

你應(yīng)該在代碼中加入你對(duì)代碼這段代碼有價(jià)值的見解注釋。

如：//出乎意料的是，對(duì)于這些數(shù)據(jù)用二叉樹比哈希表要快40%

//哈希運(yùn)算的代價(jià)比左右比要大的多

這段注釋會(huì)告訴讀者一些重要的性能信息，防止他們做無謂的優(yōu)化。

• 為代碼中的不足寫注釋

代碼始終在演進(jìn)，并且在代碼中肯定會(huì)有不足。

要把這些不足記錄下來以便后來人完善。

如當(dāng)代碼需要改進(jìn)時(shí)：

//TODO:嘗試優(yōu)化算法

如當(dāng)代碼沒有完成時(shí)：

//TODO:處理JPG以外的圖片格式

你應(yīng)該隨時(shí)把代碼將來該如何改動(dòng)的想法用注釋的方式記錄下來。這種注釋給讀者帶來對(duì)代碼質(zhì)量和當(dāng)前狀態(tài)的寶貴見解，甚至?xí)o他們指出如何改進(jìn)代碼的方向。

• 對(duì)意料之中的疑問添加注釋

當(dāng)別人讀你的代碼的時(shí)候，有些部分可能讓他們有這樣的疑問："為什么要這樣寫？"你的工作就是要給這些部分加上注釋。

如：

// 因?yàn)镃onnection的創(chuàng)建很耗費(fèi)資源和時(shí)間，而且需要多線程訪問，

// 所以使用多線程單例模式

publicstaticConnection Instance

{

get

{

if(_instance==null)

{

lock (_lock)

{

if (_instance ==null)

{

_instance =newConnection();

}

}

}

return _instance;

}

}

• 公布可能的陷阱

當(dāng)為一個(gè)函數(shù)或者類寫注釋時(shí)，可以這樣的問自己:"這段代碼有什么出人意料的地方嗎？會(huì)不會(huì)被無用？"。基本上說就是你需要未雨綢繆，預(yù)料到別人使用你代碼時(shí)可能遇到的問題。如：

//XXX: 因?yàn)檎{(diào)用外部郵件服務(wù)器發(fā)送郵件，所以耗時(shí)較長，請(qǐng)使用異步方法調(diào)用以防止UI卡死。

publicvoid SendEmail(string to, string subject, string body)

• 對(duì)于代碼塊總結(jié)性地注釋

對(duì)于代碼塊的總結(jié)性注釋可以使讀者在深入細(xì)節(jié)之前就能得到該代碼塊的主旨，甚至有時(shí)候都可以直接跳過該代碼塊，從而可以快速準(zhǔn)確的把握代碼。

如讀者看到：//下面代碼使用了二分查找算法來快速的根據(jù)用戶Id找到相應(yīng)用戶

那么他就可以快速理解下面代碼的邏輯，否則自己看二分查找還是要用些時(shí)間的。