【.NET机房重构】——注释新解

    记得在学习.NET视频的时候遇见过一个名词——XML，其实这也不是第一次遇见，早前也遇见过，上网查了一下就知道是可扩展标记语言，但是具体是什么意思怎么用，查了好几遍还是没搞懂。直到做到重构需要写注释的时候才发现，VS中有些自动生成的注释就可以存储为XML文件，再反过来理解XML，可扩展标记语言其实就类似于代码注释，就是对代码的扩充解释的部分，只不过XML不仅仅是这些而已。

    从第一遍做机房的时候，就要求要对自己的代码写注释，但是当时还不能完全理解什么是注释，只是知道注释是解释代码的，但是它具体怎么用或者它还有什么别的功能，这些都不清楚，于是在VB版的机房里面，我的代码注释都是这样的：

<span style="font-family:KaiTi_GB2312;font-size:18px;">Private Sub cmdCheck_Click()
'判断卡号是否为空
  If Trim(txtInputCardNo.Text) = "" Then
    MsgBox "请输入卡号！", vbOKOnly + vbExclamation, "提示"
    Exit Sub
  Else
    If Not IsNumeric(txtInputCardNo.Text) Then
      MsgBox "卡号请输入数字", vbOKOnly + vbExclamation, "提示"
      Exit Sub
    Else
      txtsql = "select * from Student_Info where cardno= '" & Trim(txtInputCardNo.Text) & "'"
      Set mrc = ExecuteSQL(txtsql, msgtext)
      '判断卡号是否存在
      If mrc.EOF = True Then
        MsgBox "此卡不存在！", vbOKOnly + vbExclamation, "提示"
        txtInputCardNo.Text = ""
        txtInputCardNo.SetFocus
      Else
      '获得对应卡号的充值信息
  '      txtsql = "select * from student_Info where "
  '      Set mrc = ExecuteSQL(txtsql, msgtext)
        txtStudentNo.Text = mrc.Fields(1)
        txtName.Text = mrc.Fields(2)
        txtSex.Text = mrc.Fields(3)
        txtDepartment.Text = mrc.Fields(4)
        txtGrade.Text = mrc.Fields(5)
        txtClass.Text = mrc.Fields(6)
        txtBalance.Text = mrc.Fields(7)
        txtComment.Text = mrc.Fields(8)
        txtStatus.Text = mrc.Fields(10)
      End If
    End If
  End If
End Sub</span>

    注释就只是实现某一个功能的功能块上的一句话，当时觉得自己的注释写的还挺对的，现在看来完全不是一回事了。

    先看看重构里面的注释：

<span style="font-family:KaiTi_GB2312;font-size:18px;">    ''' <summary>
    ''' 登录前的逻辑判断
    ''' </summary>
    ''' <param name="User"></param>
    ''' <returns>flag布尔值</returns>
    ''' <remarks></remarks>
    Public Function Login(ByVal User As Entity.UserInfo) As Boolean
        
    End Function</span>

     这是某一个方法的注释，我只是放了一个方法名上去，具体内容没写。

<span style="font-family:KaiTi_GB2312;font-size:18px;">'/***************************************************************
'类名称：Class1
'命名空间：BLL
'创建时间：2014/12/7 17:26:47
'作者：冯尧
'版本号：v1.0.0
'****************************************************************/
Public Class Class1

End Class</span>

    这是一个类头的注释，下面是相应注释的类。不管是上面的方法的注释，还是下面的类头注释，都是VS自动生成的。不只是方便自己一说，同样还方便别人。米老师经常说：我们写的代码不是给我们自己看的，是给别人看的，要让别人看的懂，那么自己的代码专业化水平就要高，我觉得这样的注释就比上面VB版的注释要专业的多。

    这两种注释都是自动生成的，但是生成的方式不同。第一种也就是某种方法的注释就是在方法名上面输入三个英文状态下的单引号就直接出来了，

<span style="font-family:KaiTi_GB2312;font-size:18px;">    ''' <summary>
    ''' 方法的功能
    ''' </summary>
    ''' <param name="Cancelcard"></param>     传入的参数名
    ''' <returns></returns>                   方法返回的东西
    ''' <remarks></remarks>                   成员的说明</span>

    

    类头的注释有一点复杂，先在VS的安装目录下找Class.vb文件（D:\工具软件\Visual Studio\Common7\IDE\ItemTemplatesCache\VisualBasic\Code\2052\Class.vb），打开该文件，输入以下代码：

<span style="font-family:KaiTi_GB2312;font-size:18px;">'/***************************************************************
'类名称：$itemname$
'命名空间：$rootnamespace$
'创建时间：$time$
'作者：冯尧
'版本号：v1.0.0
'****************************************************************/
Public Class $safeitemname$

End Class</span>

    这样的话再新建类的时候就可以直接生成类头注释了，下面是注释模板里面的一些参数
                                                 

参数	描述
clrversion	当前系统CLR版本号
GUID [1-10]	生成全局唯一标识符,可以生成10个 (例如:guid1)
itemname	打开添加新建项时输入的文件名称
machinename	当前机器的名称(如:XXXX)
registeredorganization	注册的组织名，可以是小组名
rootnamespace	当前系统的根命名空间
safeitemname	保存的文件名，名称移除了不安全的字符和空格
time	当前系统时间,格式:DD/MM/YYYY 00:00:00.
userdomain	用户所在的域
username	当前系统用户名
year	当前系统年份 YYYY

总结

    我们一直在强调全心全意为人民服务，但是具体应该怎么做，代码注释就是很好地体现。VS为我们用户提供了方便，我们给代码写注释有给那些看我们代码的人方便，微软很好地做到了为人民服务，那么就让我们把这份精神传递下去！！