程序師世界是廣大編程愛好者互助、分享、學習的平台,程序師世界有你更精彩!
首頁
編程語言
C語言|JAVA編程
Python編程
網頁編程
ASP編程|PHP編程
JSP編程
數據庫知識
MYSQL數據庫|SqlServer數據庫
Oracle數據庫|DB2數據庫
 程式師世界 >> 編程語言 >> .NET網頁編程 >> C# >> C#入門知識 >> 自己總結的C#編碼規范--4.注釋篇,

自己總結的C#編碼規范--4.注釋篇,

編輯:C#入門知識

自己總結的C#編碼規范--4.注釋篇,


  • 注釋

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

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

  • 注釋約定

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

  • 類注釋約定

/// <summary>

/// 類說明

/// </summary>

public class BinaryTree

  • 類屬性注釋約定

/// <summary>

/// 屬性說明

/// </summary>

; }

  • 方法注釋約定

/// <summary>

/// 方法說明

/// </summary>

/// <param name="parentNode">參數說明</param>

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

 parentNode)

  • 代碼間注釋約定

  • 何時寫注釋的約定

  • 如果客戶方沒有對注釋特殊要求,那麼按照下文中討論的只在需要的地方加注釋。不要加無謂的注釋。
    • 常用注釋標識的約定

    這裡約定下以後團隊常用幾種注釋標識及含義:

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

    public class BinaryTree

    {

    /// <summary>

    /// Total counts of the nodes

    /// </summary>

    public int NodesCount { get; private set; }

    /// <summary>

    /// All the nodes in the tree

    /// </summary>

    public List<BinaryNode> Nodes { get; set; }

     

    /// <summary>

    /// Insert a node to the tree

    /// </summary>

    /// <param name="node">the node you want insert into the tree</param>

     node)

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

    寫注釋常見的動機之一就是試圖來使糟糕的代碼能讓別人看懂。對於這種"拐杖式注釋",我們不需要,我們要做的是把代碼改的能夠更具有"自我說明性"。

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

    如下面這段函數的注釋

    //Enforce limits on the reply as stated in the request

    //such as the number of items returned, or total byte size,etc.

     reply)

    既然知道這個函數名會讓人很難讀懂,那麼為什麼不直接改好名字呢?這樣所有調用這個函數的地方都能很快速知道這個函數的作用,不用再跟進來看函數的作用。

    public void 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的創建很耗費資源和時間,而且需要多線程訪問,

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

    public static Connection Instance

    {

    get

    {

    if(_instance==null)

    {

    lock (_lock)

    {

    if (_instance == null)

    {

    _instance = new Connection();

    }

    }

    }

    return _instance;

    }

    }

    • 公布可能的陷阱

    當為一個函數或者類寫注釋時,可以這樣的問自己:"這段代碼有什麼出人意料的地方嗎?會不會被無用?"。基本上說就是你需要未雨綢缪,預料到別人使用你代碼時可能遇到的問題。如:

    //XXX: 因為調用外部郵件服務器發送郵件,所以耗時較長,請使用異步方法調用以防止UI卡死。

    public void SendEmail(string to, string subject, string body)

    • 對於代碼塊總結性地注釋

    對於代碼塊的總結性注釋可以使讀者在深入細節之前就能得到該代碼塊的主旨,甚至有時候都可以直接跳過該代碼塊,從而可以快速准確的把握代碼。

    如讀者看到://下面代碼使用了二分查找算法來快速的根據用戶Id找到相應用戶

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

    1. 上一頁:
    2. 下一頁:
    Copyright © 程式師世界 All Rights Reserved