C#注釋——愛你不是兩三天

說到注釋這個東東，我不得不說：愛你不是兩三天，每天卻想你很多遍、、、原來梁靜茹同學這首歌不全然是情歌啊~

 

一句注釋也沒有的一大片的代碼有木有

看着那些無名者寫的神秘代碼，有沒有罵一句，你妹的、、、

幾千行的代碼里邊全是注釋掉的東東有木有

為什么你寫的類庫沒人用啊，因為我看不懂，你可以說我是小白，但是其他人貌似也一樣

、、、、、、

 

沒有注釋的日子里，程序員只能感嘆一聲：悲慘世界

那有了注釋呢，情況貌似是這樣的：自從用上了好的注釋，我寫代碼也不頭疼了，腰板也值了，一口氣寫到5千行，不費勁，你值得擁有！

 

那C#里邊也就三種注釋，僅此而已，用好了你好我好團隊好，那就吐糟一下他們吧！

 

A、單行注釋

這個僅僅用於注釋單行的代碼，以"//" 開始，可以從一行的任何處開始，還有快捷鍵可用哦“Ctrl +K+C”

string distinctstring = string.Empty; // 根據此字段是否為空來判斷是否需要統計所查數據中的酒店數量

也有些人愣是侮辱我等程序猿的智商

if (a > 0)         //如果a大於0
 console.write(a)；//輸出變量a

 B、多行注釋

以“/*”開始，以“*/”結束，這兩個標記中間的東東全是注釋

/********************************
     * 版    本：xxx       
     * 類 名 稱：xxx       
     * 機器名稱：xxx       
     * 命名空間：xxx       
     * 文 件 名 ：xxx       
     * 創建時間：xxx       
     * 作   者：xxx
     * 說   明：xxx
     * 修改時間：xxx
     * 修 改 人：xxx

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

C、xml注釋

你只需要在vs中按“///”，它就會自動添加，你再填入相關的東東即可，這個形式的注釋還可以生成XML注釋文檔的哦

/// <summary>
        /// 返回酒店運營數據
        /// </summary>
        /// <param name="strSql">sql執行語句</param>
        /// <returns>返回datatable數據</returns>
        public DataTable GetHotelOperatorsData(string strSql)
        {
            DataSet ds = SqlHelper.ExecuteDataset(SqlHelper.CrsString, CommandType.Text, strSql);
            var myCharData = new DataTable();
            if (ds!=null)
            {
                myCharData = ds.Tables[0];
            }
            return myCharData;
        }

至於生成xml文檔，就是在標注完成后通過項目的屬性面板中的生成選項導出xml文件

勾選xml文檔文件，F6生成解決方案后，即可在輸出路徑下找到對應文件

總結：

1、在程序中可以臨時注釋掉某些代碼達到調試的目的

2、不用的注釋要刪除掉，要不然影響性能的

3、要分類注釋，比如類的注釋，方法的注釋，整個文件頭的注釋等

4、盡量讓你的注釋風格統一，同時能夠美觀一點

5、寫代碼的時候就添加，不要指望以后再弄

6、保持注釋是最新版本

7、團隊開發代碼時，使用todo注釋，說明此處代碼還沒有開發完成

 public GetData()
     {
         //
         // TODO: Add Logic here
         //
     }

8、每個文件頭必須注釋，保持這個習慣

// <copyright file="文件名.cs" company="HP">
//  Copyright (c) WW. All rights reserved.
// </copyright>
// <author>×××</author>
// <date> yyyy-mm-dd </date>
// <summary>文件功能描述</summary>
// <modify>
//      修改人：×××
//      修改時間：yyyy-mm-dd
//      修改描述：×××
//      版本：1.0
//</modify>

9、類、接口等注釋

/// <summary>
    /// 類功能的說明
    /// </summary>
    /// <see cref=""></see>
    /// <remarks>
    /// 創建人：WANG
    /// 創建日期：yyyy-mm-dd
    /// 修改人：LI
    /// 修改日期：yyyy-mm-dd
    /// 修改備注：無
    /// 版本：1.0
    /// </remarks>
    public class Student : Person
    {
     //code
    }

10、方法事件等注釋

        /// <summary>
        /// 根據員工編號獲得員工信息
        /// </summary>
        /// <param name="employeeId">員工編號</param>
        /// <exception cref="System.Exception">系統異常</exception>
        /// <returns>員工姓名</returns>
        /// <remarks>
        /// 創建人：WANG
        /// 創建日期：yyyy-mm-dd
        /// 修改人：LI
        /// 修改日期：yyyy-mm-dd
        /// 修改備注：無
        /// 版本：1.1
        /// </remarks>
        public string GetEmployeeNameById(int employeeId)
        {
            try
            {
                return "ddd";
            }
            catch (System.Exception)
            {
                throw;
            }
}

 

附件：注釋標簽，你也可以自定義標簽，之后會在生成的xml注釋文檔里有所體現

 

標簽	用法	作用
<c>	c>text</c>   text 希望將其指示為代碼的文本。	為您提供了一種將說明中的文本標記為代碼的方法。使用 <code> 將多行指示為代碼
<para>	<para>content</para> content段落文本。	用於諸如 <remarks> 或 <returns> 等標記內，使您得以將結構添加到文本中。
<param>	<param name='name'>description</param> name 為方法參數名。將此名稱用單引號括起來 (' ')。	應當用於方法聲明的注釋中，以描述方法的一個參數。
<paramref>	<paramref name="name"/> name 要引用的參數名。將此名稱用雙引號括起來 (" ")。	<paramref> 標記為您提供了一種指示詞為參數的方法。可以處理 XML 文件，從而用某種獨特的方法格式化該參數。
<see>	<see cref="member"/>   cref = "member" 對可以通過當前編譯環境進行調用的成員或字段的引用。編譯器檢查到給定代碼元素存在后，將 member 傳遞給輸出 XML 中的元素名。必須將 member 括在雙引號 (" ") 中。	使您得以從文本內指定鏈接。使用 <seealso> 指示希望在“請參閱”一節中出現的文本。
<seealso>	<seealso cref="member"/> cref = "member" 對可以通過當前編譯環境進行調用的成員或字段的引用。編譯器檢查到給定代碼元素存在后，將 member 傳遞給輸出 XML 中的元素名。必須將 member 括在雙引號 (" ") 中	使您得以指定希望在“請參閱”一節中出現的文本。使用 <see> 從文本
<example>	<example>description</example> description 代碼示例的說明。	使用 <example> 標記可以指定使用方法或其他庫成員的示例。一般情況下，這將涉及到 <code> 標記的使用。
<code>	<code>content</code> content 為希望將其標記為代碼的文本。	記為您提供了一種將多行指示為代碼的方法。使用 <c> 指示應將說明中的文本標記為代碼
<summary>	<summary>description</summary> 此處description 為對象的摘要。	應當用於描述類型成員。使用 <remarks> 以提供有關類型本身的信息。
<exception>	<exception cref="member">description</exception> cref = "member" 對可從當前編譯環境中獲取的異常的引用。編譯器檢查到給定異常存在后，將 member 轉換為輸出 XML 中的規范化元素名。必須將 member 括在雙引號 (" ") 中。 description 說明。	<exception> 標記使您可以指定類能夠引發的異常。
<include>	<include file='filename' path='tagpath[@name="id"]' /> filename 包含文檔的文件名。該文件名可用路徑加以限定。將 filename 括在單引號中 (' ')。 Tagpath：filename 中指向標記名的標記路徑。將此路徑括在單引號中 (' ')。 name 注釋前邊的標記中的名稱說明符；名稱具有一個 id。 id 位於注釋之前的標記的 id。將此 id 括在雙引號中 (" ")。	<include> 標記使您得以引用描述源代碼中類型和成員的另一文件中的注釋。這是除了將文檔注釋直接置於源代碼文件中之外的另一種可選方法。 <include> 標記使用 XML XPath 語法。有關自定義 <include> 使用的方法，請參閱 XPath 文檔。
<list>	<list type="bullet" | "number" | "table">    <listheader>       <term>term</term>       <description>description</description>    </listheader>    <item>       <term>term</term>       <description>description</description>    </item> </list>   term  定義的項，該項將在 text 中定義。 description  目符號列表或編號列表中的項或者 term 的定義。	<listheader> 塊用於定義表或定義列表中的標題行。定義表時，只需為標題中的項提供一個項。 列表中的每一項用 <item> 塊指定。創建定義列表時，既需要指定 term 也需要指定 text。但是，對於表、項目符號列表或編號列表，只需為 text 提供一個項。 列表或表所擁有的 <item> 塊數可以根據需要而定。
<permission>	<permission cref="member">description</permission>   cref = "member" 對可以通過當前編譯環境進行調用的成員或字段的引用。編譯器檢查到給定代碼元素存在后，將 member 轉換為輸出 XML 中的規范化元素名。必須將 member 括在雙引號 (" ") 中。 description  成員的訪問的說明。	<permission> 標記使您得以將成員的訪問記入文檔。System.Security.PermissionSet 使您得以指定對成員的訪問。
<remarks>	<remarks>description</remarks> description 成員的說明。	<remarks> 標記是可以指定有關類或其他類型的概述信息的位置。<summary> 是可以描述該類型的成員的位置。
<returns>	<returns>description</returns> description 返回值的說明。	<returns> 標記應當用於方法聲明的注釋，以描述返回值。
<value>	<value>property-description</value> property-description 屬性的說明。	<value> 標記使您得以描述屬性。請注意，當在 Visual Studio .NET 開發環境中通過代碼向導添加屬性時，它將會為新屬性添加 <summary> 標記。然后，應該手動添加 <value> 標記以描述該屬性所表示的值。