天轟穿C#教程之注釋

　　在C#代碼中，另一個常見的語句是注釋。注釋並不是嚴格意義上的C#代碼，但代碼最好有注釋。注釋就是解釋，即給代碼添加描述性文本

　　

　　編譯器會忽略這些內容（在本系列的Sql Server 2008書中也有詳細講到為什麼要用注釋）。在開始處理比較長的程式碼片段時，注釋可用於給進行中的工作添加提示，例如在本書第一章中那兩個執行個體中，我們自己寫的代碼上都寫了注釋。C#添加註釋的方式有兩種。可以在注釋的開頭和結尾分別放置"/*"和" */"標記，也可以如上一章執行個體中那樣使用一個標記"//"，不過使用這種方式的注釋，是不能換行的哦。也就是說一個 // 符號只能代表注釋一行。

　　

　　要使用第一種方式標記注釋，可以在注釋的開頭加上"/*"，在末尾加上"*/"。這些注釋符號可以在單獨一行上，也可以在不同的行上，注釋符號之間的所有內容都是注釋。

　　

　　在C#中，對於一個類檔進行總體說明，常常會用到這種注釋方式，如下代碼頂部的注釋是針對當前檔案的說明：

　　

　　/*----------------------------------------------------------------------------------

　　

　　* 著作權說明：本代碼檔為***著作權，未經本公司

　　

　　* 書面授權任何人或公司不得使用此檔中的部分和全部內容

　　

　　* 單元名稱：Guide_Star

　　

　　* 單元描述：導遊等級星業務類，主要實現對導遊星級的SIDU操作；

　　

　　*           實現針對不同的星級擷取導遊列表；

　　

　　*           星級規則的商務邏輯；

　　

　　* 建立人：老田

　　

　　* 版本：1.0

　　

　　* 建立日期：2010-01-11

　　

　　* ----------------修改日誌-------------------------

　　

　　* 修改人修改日期修改內容

　　

　　* 小天2010-01-15添加根據任意欄位查詢的方法

　　

　　----------------------------------------------------------------------------------*/

　　

　　using System;

　　

　　using System.Data;

　　

　　{

　　

　　///<summary>

　　

　　///導遊等級星業務類。

　　

　　///</summary>

　　

　　publicclassGuide_Star

　　

　　{

　　

　　//這是第二種注釋方式，對單句的注釋

　　

　　privatereadonly LonelyBag.DAL.Guide_Star dal=new LonelyBag.DAL.Guide_Star();

　　

　　public Guide_Star()

　　

　　{}

　　

　　成員方法代碼

　　

　　}

　　

　　}

　　

　　另一個添加註釋的方法是用"//"開始一個注釋，其後可以編寫任何內容，只要這些內容在一行上即可。下面的語句是正確的，例如上面代碼中

　　

　　//這是第二種注釋方式，對單句的注釋

　　

　　使用這種注釋是不可換行的，例如下面的語句會失敗，因為第二行代碼會解釋為C#代碼：

　　

　　//這是第二種注釋方式，

　　

　　對單句的注釋

　　

　　這類注釋可用於對單獨一行C#語句的說明，因為它們都放在一行上：

　　

　　小天：在你上面的執行個體中，我還看到這注釋，是什麼意思？

　　

　　

　　

　　///<summary>

　　

　　///導遊等級星業務類。

　　

　　///</summary>

　　

　　老田：這是C#的第三類注釋，嚴格地說，這是//文法的擴充。它們都是單行注釋，用三個"/"符號來開頭，而不是兩個。

　　

　　這種方式主要用於對類和類成員進行描述，而使用起來比第一種（前後用/*  */）還要簡單。將游標放在需要加這種注釋的地方，連續敲擊三個"/"即可。如果是對類描述就會產生上面那種形式，如果是對方法的就則自動根據方法的參數和傳回型別等產生更詳細的注釋格式。

　　

　　在正常情況下，編譯器會忽略它們，就像其它注釋一樣，但可以配置VS，在編譯項目時，提取這些注釋後面的文本，建立一個特殊格式的文字檔，該檔可用於建立文檔說明書。

　　

　　小天：上面角括弧中那個summary是什麼意思？

　　

　　老田：這個是這一類注釋的XML標記，下表說明這一類XML標記以及其作用

　　

　　標記 說明

　　

　　<c> 把行中的代碼標記為代碼，例如<c> if(i>=10);</c>

　　

　　<code> 把多行標記為代碼

　　

　　<example> 標記為一個程式碼範例

　　

　　<exception> 說明一個異常類

　　

　　<include> 包含其它文檔說明檔案的注釋

　　

　　<list> 把列表插入到文檔說明中

　　

　　<para> 標記方法的參數

　　

　　<param> <param name='name'>description</param>

　　

　　Name是方法中參數的名稱，description是參數的說明

　　

　　<paramref> 表示一個單詞是方法的參數

　　

　　<permission> 說明對成員的訪問

　　

　　<remarks> 給成員添加描述

　　

　　<returns> 說明方法的傳回值

　　

　　<see> 提供對另一個參數的交叉引用

　　

　　<seealso> 提供描述中的"參見"部分

　　

　　<summary> 提供類型或者成員的簡短小結

　　

　　<typeparam> 文本將顯示在物件瀏覽器程式碼結構 Web 報告的 IntelliSense 中。

　　

　　<typeparam  name="name">description</typeparam>

　　

　　Name是參數名，description是參數說明

　　

　　<typeparamref> 文檔檔的使用者能夠以某種獨特的方式設定單詞的格式，例如以斜體顯示。

　　

　　<typeparamref  name="name"/>

　　

　　Name是型別參數的名稱

　　

　　<value> 描述屬性

　　

　　接下來我們具體的樣本，下面樣本中除灰色的符號和字型都是由"在方法體上連續敲三個"/"後"自動產生的，所以不用覺得太多。

　　

　　///<summary>

　　

　　///對這個方法的簡要說明

　　

　　///</summary>

　　

　　///<param name="min">參數min的說明</param>

　　

　　///<param name="max">參數max的說明</param>

　　

　　///<returns>傳回值的描述</returns>

　　

　　publicint GetCount(int min, int max)

　　

　　{

　　

　　//逗你玩

　　

　　}

　　

　　本文為天轟穿原著，轉載請註明出處及作者！