在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>
类、方法、属性等;