在C#当中使用注释
2008-08-06 15:58
204 查看
在C#当中使用注释
2008年05月31日 13:55:28 作者: 紫色思念
2008年05月31日 13:55:28 作者: 紫色思念
由于软件的复杂性以及不可预知性,所以在程序当中添加注释是一个非常明智的选择,尤其是在团队开发当中,可以使自己的程序更加适于阅读。 我们知道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>标识符之外,微软还提供了其它的标识符,下面我们进行逐一的介绍:
对于这些东西进行了解释之后,我们现在给出一个详细的示例给大家,现在让我们来看看这些标识符为我们带来的多种便利(在这儿,我假设各位手中都已经有了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中新增加的这种注释方法,给团队开发提供了更加方便的手段,来加强团队成员之间的联系,同时个体编程人员也从中得到了更多的好处,所以在编写你自己的程序时,我们最好都多敲几个单词,对自己的程序加入这种格式的注释! |
相关文章推荐
- 在C#当中使用注释
- 在C#当中使用注释
- C#编写中使用预编译指令代替不停的注释
- C#注释的正确使用方法(Delphi与此类似)
- C#注释的一些使用方法浅谈
- C# 学习笔记 -- 第二天 使用注释提高代码可读性
- 使用C#给PDF文档添加注释的实现代码
- C#编写中使用预编译指令代替不停的注释
- 在Csharp当中使用注释
- c#中有关Xml注释的使用和生成
- c#使用中文注释和显示乱码问题(unity3d)
- .NET -> c# 注释的正确的使用方法
- 使用C#重写网上的60行 Javascript 俄罗斯方块源码 (带注释)
- c#注释 使用方法
- C#调用C++方法,C#使用c++方法返回类或结构体
- 使用C#进行Word 2002和Excel 2002编程
- C# 使用SqlBulkCopy类批量复制大数据
- (转)在C#中使用WIA获取扫描仪数据(二、WIA Automation Layer)
- C# 递归函数详细介绍及使用方法
- 33、C#里面的进度条和时钟组件的使用