在Csharp當(dāng)中使用注釋

注意：本文是開(kāi)心就好原創(chuàng)，并且曾經(jīng)發(fā)表在《視窗世界》中，不歡迎轉(zhuǎn)貼，十分感謝�。�！
由于軟件的復(fù)雜性以及不可預(yù)知性，所以在程序當(dāng)中添加注釋是一個(gè)非常明智的選擇，尤其是在團(tuán)隊(duì)開(kāi)發(fā)當(dāng)中，可以使自己的程序更加適于閱讀。
我們知道Csharp（即C#）作為C++語(yǔ)言的一種擴(kuò)展版本，繼承了C++的注釋方法，即以“//”針對(duì)一行的注釋方法，或者以“/* */”跨行的注釋方法�？梢院芊奖闼�有開(kāi)發(fā)人員進(jìn)行使用。
例一：

/*
Author：開(kāi)心就好
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語(yǔ)句;
}
}
說(shuō)明：在這段簡(jiǎn)單的程序當(dāng)中，我們使用了兩種簡(jiǎn)單的注釋方法，首先，我們知道“/**/”方法適合跨行注釋。一般來(lái)說(shuō)，我們?cè)谝粋�(gè)程序體的首部都會(huì)使用這種方法對(duì)整個(gè)文件作一個(gè)簡(jiǎn)單的描述。
而以//開(kāi)始的注釋語(yǔ)句其有效范圍僅從該符號(hào)至該行末尾，//符號(hào)既可以放置在行首，亦可以在這一行的任意位置。
同時(shí)，我們要注意，在可能的情況下請(qǐng)不要使用嵌套注釋語(yǔ)句，雖然有些編譯器可以自動(dòng)處理這些嵌套的注釋語(yǔ)句，但作為一個(gè)良好的程序員，在其編程中應(yīng)該養(yǎng)成一個(gè)良好的習(xí)慣，盡量避免這種情況的發(fā)生。
例二：
/*
Author：開(kāi)心就好
Version: 1.1
Date: 2001/6/19
Description：對(duì)Test類進(jìn)行合理的擴(kuò)展
*/
public class test{
 public static void Main(){
/*
//這是一個(gè)嵌套注釋，是一種不合理的狀態(tài)
*/
System.Console.WriteLine (“Hello,World”);
}

通過(guò)以上兩組例子，我們現(xiàn)在已經(jīng)對(duì)注釋有了基本的了解，但是如果僅是這些語(yǔ)句，可能就不根本不值得進(jìn)行這樣大篇幅的介紹，所以現(xiàn)在我們開(kāi)始引入Csharp當(dāng)中專用的一種注釋方法――“///”，并且對(duì)這種注釋方法作詳細(xì)的介紹。
Csharp引用的這種注釋方法，原則上與原有的“//”相兼容，也是一種單行注釋方法，但由于其新增加了一些注釋語(yǔ)句，并且在VS.NET當(dāng)中進(jìn)行了相應(yīng)的集成，使其功能更加強(qiáng)大。
例三：
/*
Author:開(kāi)心就好
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)識(shí)符。但在這兒我們可能還沒(méi)有體會(huì)到它有什么具體的用處，相反，對(duì)于一些手寫(xiě)代碼的朋友來(lái)說(shuō)，我們可能還感覺(jué)到這樣去寫(xiě)可能還增加了一些負(fù)擔(dān)，因?yàn)橛忠�多敲入幾個(gè)單詞。
且慢，下面我們開(kāi)始對(duì)這個(gè)程序進(jìn)行編譯，我們知道，Csharp的編譯命令為CSC，如果大家對(duì)這個(gè)命令進(jìn)行過(guò)仔細(xì)的研究的話，我們可以看到它有一個(gè)參數(shù)為/doc，那這個(gè)參數(shù)有什么用呢？
下面，我們將例三的文件存為C:\test.cs，并且使用如下的命令行進(jìn)行編譯：
csc /t:exe /doc:test.xml test.cs
下面我們看一下C盤(pán)根目錄中，會(huì)出現(xiàn)一個(gè)新的XML文件，即test.xml，使用瀏覽器打開(kāi)，其文件內(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>
到目前為止，我們可能仍然沒(méi)有看出來(lái)，這東西有什么用處。只不過(guò)多產(chǎn)生了一個(gè)XML文件而已。
如果在座的各位也有Java程序員，可能對(duì)此更是不屑一顧，因?yàn)樵贘ava編譯工具當(dāng)中，提供了JavaDoc文件，對(duì)Java程序當(dāng)中的注釋進(jìn)行整理，并且生成一個(gè)可讀的HTML文件，可以作為一個(gè)類的說(shuō)明手冊(cè)。
其實(shí)CSC的DOC參數(shù)也是起類似的作用的，不過(guò)它只是生成了一個(gè)中間的XML數(shù)據(jù)文件。利用VS.NET提供的強(qiáng)大功能，這個(gè)XML數(shù)據(jù)文件會(huì)形成一個(gè)強(qiáng)大的說(shuō)明文件，甚至在團(tuán)隊(duì)開(kāi)發(fā)當(dāng)中，你只要寫(xiě)清楚這些注釋語(yǔ)句就可以自動(dòng)產(chǎn)生一個(gè)詳細(xì)設(shè)計(jì)文檔，而不必在寫(xiě)完程序后自己再動(dòng)手寫(xiě)這么一份文檔。
在CSC的注釋語(yǔ)句中，除了<Summary>標(biāo)識(shí)符之外，微軟還提供了其它的標(biāo)識(shí)符，下面我們進(jìn)行逐一的介紹：

標(biāo)