旧文重贴：在Csharp当中使用注释（原创）

在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中新增加的这种注释方法，给团队开发提供了更加方便的手段，来加强团队成员之间的联系，同时个体编程人员也从中得到了更多的好处，所以在编写你自己的程序时，我们最好都多敲几个单词，对自己的程序加入这种格式的注释！

原文转自：http://www.ltesting.net