舊文重貼:在Csharp當中使用注釋(原創)

來源:互聯網
上載者:User
原創

在Csharp當中使用注釋


注意:本文是開心就好原創,並且曾經發表在《視窗世界》中,不歡迎轉貼,十分感謝!!!
由於軟體的複雜性以及不可預知性,所以在程式當中添加註釋是一個非常明智的選擇,尤其是在團隊開發當中,可以使自己的程式更加適於閱讀。
我們知道Csharp(即C#)作為C++語言的一種擴充版本,繼承了C++的注釋方法,即以“//”針對一行的注釋方法,或者以“/*   */”跨行的注釋方法。可以很方便所有開發人員進行使用。
例一

/*
Author:開心就好
Version:1.0
Date:: 2001/6/19
Description:構建一個Test類
*/
public class test{
       //本類僅有一個公用方法
       public static void Main(){
       System.Console.WriteLine (“Hello,world”);//輸出Hello,World語句;
}
}
說明:在這段簡單的程式當中,我們使用了兩種簡單的注釋方法,首先,我們知道“/**/”方法適合跨行注釋。一般來說,我們在一個程式體的首部都會使用這種方法對整個檔案作一個簡單的描述。
而以//開始的備註陳述式其有效範圍僅從該符號至該行末尾,//符號既可以放置在行首,亦可以在這一行的任意位置。
同時,我們要注意,在可能的情況下請不要使用嵌套備註陳述式,雖然有些編譯器可以自動處理這些嵌套的備註陳述式,但作為一個良好的程式員,在其編程中應該養成一個良好的習慣,盡量避免這種情況的發生。
例二:
/*
Author:開心就好
Version: 1.1
Date: 2001/6/19
Description:對Test類進行合理的擴充
*/
public class test{
       public static void Main(){
              /*
              //這是一個嵌套注釋,是一種不合理的狀態
*/
              System.Console.WriteLine (“Hello,World”);
}

通過以上兩組例子,我們現在已經對注釋有了基本的瞭解,但是如果僅是這些語句,可能就不根本不值得進行這樣大篇幅的介紹,所以現在我們開始引入Csharp當中專用的一種注釋方法――“///”,並且對這種注釋方法作詳細的介紹。
Csharp引用的這種注釋方法,原則上與原有的“//”相相容,也是一種單行注釋方法,但由於其新增加了一些備註陳述式,並且在VS.NET當中進行了相應的整合,使其功能更加強大。
例三:
/*
Author:開心就好
Version:1.2
Date:2001/6/18
Description:構建一個Test類
*/
///<Summary>一個Test類</Summary>
public class test{
       ///<Summary>入口方法</Summary>
       public static void Mial(){
              System.Console.WriteLine(“Hello,World”);
       }
}
我們可以看看與前面的注釋有哪方面的不同。首先我們注意到增加了一個<Summary>的標識符。但在這兒我們可能還沒有體會到它有什麼具體的用處,相反,對於一些手寫代碼的朋友來說,我們可能還感覺到這樣去寫可能還增加了一些負擔,因為又要多敲入幾個單詞。
且慢,下面我們開始對這個程式進行編譯,我們知道,Csharp的編譯命令為CSC,如果大家對這個命令進行過仔細的研究的話,我們可以看到它有一個參數為/doc,那這個參數有什麼用呢?
下面,我們將例三的檔案存為C:\test.cs,並且使用如下的命令列進行編譯:
csc /t:exe /doc:test.xml test.cs
下面我們看一下C盤根目錄中,會出現一個新的XML檔案,即test.xml,使用瀏覽器開啟,其檔案內容為:
<?xml version="1.0" ?>
- <doc>
- <assembly>
<name> test</name>
</assembly>
- <members>
- <member name=" T:test">
<Summary> 一個Test類</Summary>
</member>
- <member name=" M:test.Main">
<Summary> 入口方法</Summary>
</member>
</members>
</doc>
到目前為止,我們可能仍然沒有看出來,這東西有什麼用處。只不過多產生了一個XML檔案而已。
如果在座的各位也有Java程式員,可能對此更是不屑一顧,因為在Java編譯工具當中,提供了JavaDoc檔案,對Java程式當中的注釋進行整理,並且產生一個可讀的HTML檔案,可以作為一個類的說明手冊。
其實CSC的DOC參數也是起類似的作用的,不過它只是產生了一個中間的XML資料檔案。利用VS.NET提供的強大功能,這個XML資料檔案會形成一個強大的說明檔案,甚至在團隊開發當中,你只要寫清楚這些備註陳述式就可以自動產生一個詳細設計文檔,而不必在寫完程式後自己再動手寫這麼一份文檔。
在CSC的備註陳述式中,除了<Summary>標識符之外,微軟還提供了其它的標識符,下面我們進行逐一的介紹:
標識符
描述及樣本
應用於
<Summary>
對整體進行概要性描述
<summary>Description</summary>
類、屬性(不推薦)、方法等
<para>
跟在Summary之後,對方法所涉及的入口參數進行有效解釋
<param name=username>本參數是使用者的帳號</param>
方法的入口參數;
<returns>
對方法的傳回值進行解釋;
<returns>傳回值零代表操作成功,-1代表操作不成功</returns>
方法的傳回值;
<remarks>
對一些語句進行備忘性描述
<remarks>本類需要調用另外一個User類相關方法</remarks>
類、方法、屬性等;
<see>
在產生的文檔中產生一個串連到其它描述的超連結;
<see cref=”[member]”/>

可以在其它注釋標識符中加入
<seealso>
與上者的區別是本標識符顯示超連結在一個文檔的尾部的“See Also”地區,而前者在文檔之中;
<seealso cref=”[member]”/>
不可以在其它注釋標識符中加入
<value>
對一個屬性進行概要性解釋;
<value>這是一個public屬性</value>
屬性
<code>
如果需要置入一部分原始碼段,可以使用本標識符將其標記出來
<code>
public int add(int a,b)
{return a+b;
}
</code>
可以在其它注釋標識符中加入
<exception>
對程式中可能拋出的異常做解釋;
<exception cref=”System.Exception”>拋出的異常情況</exception>
在方法當中如果有拋出異常,如“try…catch結構”時可以使用本標識符做解釋
<permission>
對方法的存取權限做一些解釋:
<permission cref=”System.Security.PermissionSet”>這是公用方法</permission>
方法,屬性
<c>
與<code>標識符基本相同,但本標識符僅用於單行代碼;
<c>return a+b;</c>
可以在其它標識符中插入使用;
<example>
舉例說明,通常與<code>配套使用;
<example> 以下樣本說明如何調用Add方法:
<code>
class MyClass
{
  public static int Main()
{
return Add(1+2);
}
}
</code>
</example>

可以在其它標識符中插入;
<paramref>
在其它地方引用一個入口參數
<paramref cref=”a”>請注意,這是一個整型參數</paramref>

備忘: 本表中的方法也可以稱之為成員函數(這是VC++ 當中慣用的名稱); 另外,關於<list> 標識符我們在此沒有做解釋,有興趣的朋友可以閱讀SDK 或者其它相關材料;

對於這些東西進行瞭解釋之後,我們現在給出一個詳細的樣本給大家,現在讓我們來看看這些標識符為我們帶來的多種便利(在這兒,我假設各位手中都已經有了Visual Studio.NET)
例四:
using System;

/// <summary>
/// ClassName:SomeClass
/// Version:1.0
/// Date:2001/6/21
/// Author:開心就好
/// </summary>
/// <remarks>
/// 本類僅是一個樣本教學類,不完成具體的工作
/// </remarks>
public class SomeClass
{
     /// <summary>
     /// 內部私人變數,儲存名稱</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>
    /// 本方法是沒有進行具體構建</summary>
    /// <param name="s"> 入口參數S是一個String類型</param>
    /// <seealso cref="String">
    ///String類型的資訊</seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// 本方法仍然沒有進行具體構建</summary>
    /// <returns>
    /// 傳回值始終為0.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// 參看SomeMethod(string)方法的說明 </seealso>
    public int SomeOtherMethod()
    {
       return 0;
    }

    /// <summary>
     /// 該應用程式的入口
    /// </summary>
    /// <param name="args"> 入口參數集合</param>
     public static int Main(String[] args)
     {
         //
         // TODO: Add code to start application here
         //

         return 0;
     }
}


下面,我們在Visual Studio.NET中將這段程式拷貝進去,然後選擇Tools菜單中的“Build Comment Web Pages…”,將彈出一個對話方塊,我們直接點擊OK之後,可以看到系統正在對這些注釋進行整理,最後將出現一個Web文檔。
這份Web文檔,我們可以使用HTML開啟,請看下圖


是不是比JavaDOC產生的注釋還要好一些呢?所有的注釋都被Visual Studio.Net分門別類的進行了整理,可以讓同一團隊中其它的人員對其一目瞭然:)
但這種注釋並不是僅是為了產生這個注釋文檔,更重要的是,它可以提供在編程中的智能提示的作用。
仍以上例來舉例說明,下面我使用了一個新的檔案,並且在這個檔案當中引用了例四中定義的一些屬性與方法,如下圖:

我們可以從圖中清楚的看到,Visual Studio.NET自動將原有的注釋加入到了智能提示當中。
我們可以想象,如果你在一個團隊當中參與開發,當團隊中其他人員需要調用你編的一段程式時,他甚至可以不必開啟你的原始碼,就可以利用Visual Studio.NET提供的強大功能來遍曆你所編寫的類檔案中的所有的屬性及方法,並且根據你寫的注釋而得到這些屬性與方法的說明!

綜上所述,微軟在Visual Studio.NET中新增加的這種注釋方法,給團隊開發提供了更加方便的手段,來加強團隊成員之間的聯絡,同時個體編程人員也從中得到了更多的好處,所以在編寫你自己的程式時,我們最好都多敲幾個單詞,對自己的程式加入這種格式的注釋!

相關關鍵詞:
相關文章

E-Commerce Solutions

Leverage the same tools powering the Alibaba Ecosystem

Learn more >

Apsara Conference 2019

The Rise of Data Intelligence, September 25th - 27th, Hangzhou, China

Learn more >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。