自己總結的C#編碼規範--4.注釋約定

標籤：des   style   blog   http   color   使用   io   2014   

• 注釋

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

當你寫代碼時，你腦海裡會有很多有價值的資訊，但當其他人讀你代碼時，這些資訊已經丟失，他們所見到的只是眼前代碼。

• 注釋約定

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

• 類注釋約定

/// <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. 單行注釋，注釋行數<3行時使用

   //單行注釋

2. 多行注釋，2<注釋行數<=10時使用

   /*多行注釋1

   多行注釋2

   多行注釋3*/

3. 註解區塊，10<注釋行數時使用，用50個*

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

   * 代碼塊注釋1

   *    代碼塊注釋2

   *    ......

   *    代碼塊注釋10

   *    代碼塊注釋11

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

• 何時寫注釋的約定

1. 以下三種情況我們需要在所有的類、類屬性和方法都必須按照上述格式編寫注釋
   1. 客戶方對代碼注釋重視程度較高
   2. 我們需要提供代碼注釋自動產生的API文檔。
   1. 目前編寫的是公用核心模組
2. 如果客戶方沒有對注釋特殊要求，那麼按照下文中討論的只在需要的地方加註釋。不要加無謂的注釋。