舊文重貼：在Csharp當(dāng)中使用注釋（原創(chuàng)）
2024-07-21 02:22:18
供稿：網(wǎng)友
在csharp當(dāng)中使用注釋
注意：本文是開心就好原創(chuàng)，并且曾經(jīng)發(fā)表在《視窗世界》中，不歡迎轉(zhuǎn)貼，十分感謝！！！
由于軟件的復(fù)雜性以及不可預(yù)知性，所以在程序當(dāng)中添加注釋是一個(gè)非常明智的選擇，尤其是在團(tuán)隊(duì)開發(fā)當(dāng)中，可以使自己的程序更加適于閱讀。
我們知道csharp（即c#）作為c++語言的一種擴(kuò)展版本，繼承了c++的注釋方法，即以“//”針對一行的注釋方法，或者以“/* */”跨行的注釋方法。可以很方便所有開發(fā)人員進(jìn)行使用。
例一：
/*
author：開心就好
version：1.0
date:： 2001/6/19
description:構(gòu)建一個(gè)test類
*/
public class test{
//本類僅有一個(gè)公共方法
public static void main(){
system.console.writeline (“hello,world”);//輸出hello,world語句;
}
}
說明：在這段簡單的程序當(dāng)中，我們使用了兩種簡單的注釋方法，首先，我們知道“/**/”方法適合跨行注釋。一般來說，我們在一個(gè)程序體的首部都會使用這種方法對整個(gè)文件作一個(gè)簡單的描述。
而以//開始的注釋語句其有效范圍僅從該符號至該行末尾，//符號既可以放置在行首，亦可以在這一行的任意位置。
同時(shí)，我們要注意，在可能的情況下請不要使用嵌套注釋語句，雖然有些編譯器可以自動(dòng)處理這些嵌套的注釋語句，但作為一個(gè)良好的程序員，在其編程中應(yīng)該養(yǎng)成一個(gè)良好的習(xí)慣，盡量避免這種情況的發(fā)生。
例二：
/*
author：開心就好
version: 1.1
date: 2001/6/19
description：對test類進(jìn)行合理的擴(kuò)展
*/
public class test{
public static void main(){
/*
//這是一個(gè)嵌套注釋，是一種不合理的狀態(tài)
*/
system.console.writeline (“hello,world”);
}
通過以上兩組例子，我們現(xiàn)在已經(jīng)對注釋有了基本的了解，但是如果僅是這些語句，可能就不根本不值得進(jìn)行這樣大篇幅的介紹，所以現(xiàn)在我們開始引入csharp當(dāng)中專用的一種注釋方法――“///”，并且對這種注釋方法作詳細(xì)的介紹。
csharp引用的這種注釋方法，原則上與原有的“//”相兼容，也是一種單行注釋方法，但由于其新增加了一些注釋語句，并且在vs.net當(dāng)中進(jìn)行了相應(yīng)的集成，使其功能更加強(qiáng)大。
例三：
/*
author:開心就好
version:1.2
date:2001/6/18
description:構(gòu)建一個(gè)test類
*/
///<summary>一個(gè)test類</summary>
public class test{
///<summary>入口方法</summary>
public static void mial(){
system.console.writeline(“hello,world”);
｝
}
我們可以看看與前面的注釋有哪方面的不同。首先我們注意到增加了一個(gè)<summary>的標(biāo)識符。但在這兒我們可能還沒有體會到它有什么具體的用處，相反，對于一些手寫代碼的朋友來說，我們可能還感覺到這樣去寫可能還增加了一些負(fù)擔(dān)，因?yàn)橛忠嗲萌霂讉€(gè)單詞。
且慢，下面我們開始對這個(gè)程序進(jìn)行編譯，我們知道，csharp的編譯命令為csc，如果大家對這個(gè)命令進(jìn)行過仔細(xì)的研究的話，我們可以看到它有一個(gè)參數(shù)為/doc，那這個(gè)參數(shù)有什么用呢？
下面，我們將例三的文件存為c:/test.cs，并且使用如下的命令行進(jìn)行編譯：
csc /t:exe /doc:test.xml test.cs
下面我們看一下c盤根目錄中，會出現(xiàn)一個(gè)新的xml文件，即test.xml，使用瀏覽器打開，其文件內(nèi)容為：
<?xml version="1.0" ?>
- <doc>
- <assembly>
<name>test</name>
</assembly>
- <members>
- <member name="t:test">
<summary>一個(gè)test類</summary>
</member>
- <member name="m:test.main">
<summary>入口方法</summary>
</member>
</members>
</doc>
到目前為止，我們可能仍然沒有看出來，這東西有什么用處。只不過多產(chǎn)生了一個(gè)xml文件而已。
如果在座的各位也有java程序員，可能對此更是不屑一顧，因?yàn)樵趈ava編譯工具當(dāng)中，提供了javadoc文件，對java程序當(dāng)中的注釋進(jìn)行整理，并且生成一個(gè)可讀的html文件，可以作為一個(gè)類的說明手冊。
其實(shí)csc的doc參數(shù)也是起類似的作用的，不過它只是生成了一個(gè)中間的xml數(shù)據(jù)文件。利用vs.net提供的強(qiáng)大功能，這個(gè)xml數(shù)據(jù)文件會形成一個(gè)強(qiáng)大的說明文件，甚至在團(tuán)隊(duì)開發(fā)當(dāng)中，你只要寫清楚這些注釋語句就可以自動(dòng)產(chǎn)生一個(gè)詳細(xì)設(shè)計(jì)文檔，而不必在寫完程序后自己再動(dòng)手寫這么一份文檔。
在csc的注釋語句中，除了<summary>標(biāo)識符之外，微軟還提供了其它的標(biāo)識符，下面我們進(jìn)行逐一的介紹：
標(biāo)識符
描述及示例
應(yīng)用于
<summary>
對整體進(jìn)行概要性描述
<summary>description</summary>
類、屬性（不推薦）、方法等
<para>
跟在summary之后，對方法所涉及的入口參數(shù)進(jìn)行有效的解釋
<param name=username>本參數(shù)是用戶的帳號</param>
方法的入口參數(shù);
<returns>
對方法的返回值進(jìn)行解釋;
<returns>返回值零代表操作成功，-1代表操作不成功</returns>
方法的返回值;
<remarks>
對一些語句進(jìn)行備注性描述
<remarks>本類需要調(diào)用另外一個(gè)user類相關(guān)方法</remarks>
類、方法、屬性等;
<see>
在生成的文檔中產(chǎn)生一個(gè)連接到其它描述的超鏈接;
<see cref=”[member]”/>
可以在其它注釋標(biāo)識符中加入
<seealso>
與上者的區(qū)別是本標(biāo)識符顯示超鏈接在一個(gè)文檔的尾部的“see also”區(qū)域，而前者在文檔之中;
<seealso cref=”[member]”/>
不可以在其它注釋標(biāo)識符中加入
<value>
對一個(gè)屬性進(jìn)行概要性解釋;
<value>這是一個(gè)public屬性</value>
屬性
<code>
如果需要置入一部分源代碼段，可以使用本標(biāo)識符將其標(biāo)記出來
<code>
public int add(int a,b)
{return a+b;
}
</code>
可以在其它注釋標(biāo)識符中加入
<exception>
對程序中可能拋出的異常做解釋;
<exception cref=”system.exception”>拋出的異常情況</exception>
在方法當(dāng)中如果有拋出異常，如“try…catch結(jié)構(gòu)”時(shí)可以使用本標(biāo)識符做解釋
<permission>
對方法的訪問權(quán)限做一些解釋：
<permission cref=”system.security.permissionset”>這是公共方法</permission>
方法，屬性
<c>
與<code>標(biāo)識符基本相同，但本標(biāo)識符僅用于單行代碼;
<c>return a+b;</c>
可以在其它標(biāo)識符中插入使用;
<example>
舉例說明，通常與<code>配套使用;
<example> 以下示例說明如何調(diào)用add方法:
<code>
class myclass
{
public static int main()
{
return add(1+2);
}
}
</code>
</example>
可以在其它標(biāo)識符中插入;
<paramref>
在其它地方引用一個(gè)入口參數(shù)
<paramref cref=”a”>請注意，這是一個(gè)整型參數(shù)</paramref>
備注：本表中的方法也可以稱之為成員函數(shù)（這是vc++當(dāng)中慣用的名稱）;另外，關(guān)于<list>標(biāo)識符我們在此沒有做解釋，有興趣的朋友可以閱讀sdk或者其它相關(guān)材料;
對于這些東西進(jìn)行了解釋之后，我們現(xiàn)在給出一個(gè)詳細(xì)的示例給大家，現(xiàn)在讓我們來看看這些標(biāo)識符為我們帶來的多種便利（在這兒，我假設(shè)各位手中都已經(jīng)有了visual studio.net）
例四：
using system;
/// <summary>
/// classname:someclass
/// version:1.0
/// date:2001/6/21
/// author:開心就好
/// </summary>
/// <remarks>
/// 本類僅是一個(gè)示例教學(xué)類，不完成具體的工作
/// </remarks>
public class someclass
{
/// <summary>
/// 內(nèi)部私有變量，存儲名稱</summary>
private string myname = null;
public someclass()
{
//
// todo: add constructor logic here
//
}
/// <summary>
/// 名稱屬性 </summary>
/// <value>
///本屬性為只讀屬性，返回用戶名</value>
public string name
{
get
{
if ( myname == null )
{
throw new exception("name is null");
}
return myname;
}
}
/// <summary>
/// 本方法是沒有進(jìn)行具體構(gòu)建</summary>
/// <param name="s"> 入口參數(shù)s是一個(gè)string類型</param>
/// <seealso cref="string">
///string類型的信息</seealso>
public void somemethod(string s)
{
}
/// <summary>
/// 本方法仍然沒有進(jìn)行具體構(gòu)建</summary>
/// <returns>
/// 返回值始終為0.</returns>
/// <seealso cref="somemethod(string)">
/// 參看somemethod(string)方法的說明 </seealso>
public int someothermethod()
{
return 0;
}
/// <summary>
/// 該應(yīng)用程序的入口
/// </summary>
/// <param name="args"> 入口參數(shù)集合</param>
public static int main(string[] args)
{
//
// todo: add code to start application here
//
return 0;
}
}
下面，我們在visual studio.net中將這段程序拷貝進(jìn)去，然后選擇tools菜單中的“build comment web pages…”，將彈出一個(gè)對話框，我們直接點(diǎn)擊ok之后，可以看到系統(tǒng)正在對這些注釋進(jìn)行整理，最后將出現(xiàn)一個(gè)web文檔。
這份web文檔，我們可以使用html打開，請看下圖
是不是比javadoc產(chǎn)生的注釋還要好一些呢？所有的注釋都被visual studio.net分門別類的進(jìn)行了整理，可以讓同一團(tuán)隊(duì)中其它的人員對其一目了然：）
但這種注釋并不是僅是為了產(chǎn)生這個(gè)注釋文檔，更重要的是，它可以提供在編程中的智能提示的作用。
仍以上例來舉例說明，下面我使用了一個(gè)新的文件，并且在這個(gè)文件當(dāng)中引用了例四中定義的一些屬性與方法，如下圖：
我們可以從圖中清楚的看到，visual studio.net自動(dòng)將原有的注釋加入到了智能提示當(dāng)中。
我們可以想象，如果你在一個(gè)團(tuán)隊(duì)當(dāng)中參與開發(fā)，當(dāng)團(tuán)隊(duì)中其他人員需要調(diào)用你編的一段程序時(shí)，他甚至可以不必打開你的源代碼，就可以利用visual studio.net提供的強(qiáng)大功能來遍歷你所編寫的類文件中的所有的屬性及方法，并且根據(jù)你寫的注釋而得到這些屬性與方法的說明！
綜上所述，微軟在visual studio.net中新增加的這種注釋方法，給團(tuán)隊(duì)開發(fā)提供了更加方便的手段，來加強(qiáng)團(tuán)隊(duì)成員之間的聯(lián)系，同時(shí)個(gè)體編程人員也從中得到了更多的好處，所以在編寫你自己的程序時(shí)，我們最好都多敲幾個(gè)單詞，對自己的程序加入這種格式的注釋！
