是雏还是鹰——编程规范之代码注释

注释能使代码更加容易理解，更加容易跟踪。出色的注释就像一幅好的设计蓝图，能够引导阅读者通过你的应用程序的曲折之处，能够说明预期的运行结果和可能出现的异常情况。注释可以为后来的维护者带来极大的方便，无论是类说明注释，方法说明注释，还是变量说明注释，这些都是不可或缺的。没了注释代码就是“天书”，有的读者可能会说花点时间来看也不费劲嘛！想象一下阅读类似于上文中的那样没有注释的几千，几万，几十万代码是多么费时费力的事，但是这些时间原本是可以通过几行注释节省的。

书接上回还是以上次文中的代码为例。可悲的是文中代码和大多数人写的代码一样——没有注释。

1.         写注释的人有着共同的特点，不写注释的人各有各的理由。

l  写注释太费时间

实际上，在编写代码时加上注释根本不需要多少时间。

l  有些过程很难注释。

通常而言，如果代码的一个部分很难注释，那么如果没有注释，其他人就更难理解你的代码。

PS：复杂而很难注释的代码也许不是什么好代码。

如果你发现难以给全部或者部分过程加上注释，那么请回头好好检查一下你的代码，你很可能会发现更好的解决办法。

2.         注释原则（摘录），供大家参考

l  不要简简单单重复代码做些什么，不能给代码增加信息的注释还不如不写。

l  用注释来说明何时可能出错和为什么出错，方便后期调试。

l  在编写代码前进行注释，以文字的形式展现你的思路。

l  增强注释的可读性，语句完整、表意清楚；格式上的缩进、对齐等美观操作也是不可少的。

l  为每个过程赋予一个注释标头，C#中的///（VB中是’’’）可以在过程调用时清楚的指导此过程的信息。

l  内部注释方面：

(1) 在每个if和select语句的前面加上注释，让读者语句因为什么而分支，不同的分支结果会是什么。

(3) 在每个循环的前面加上注释，保证读者明白此循环的作用。

(4) 在修改了全局变量（如果有的话）的每个语句前面加上注释，方便后期代码调试。

修改后的代码

    ''' <summary>
    ''' 将DataGridview中的数据导出到Excel
    ''' <summary>
    ''' <param name="dgvSouse">要导出到Excel的DataGridView<param>
    ''' <param name="blnIsOnlyVisible">判断是否添加所有DataGridView中的内容<param>
    ''' <remarks><remarks>
    Sub ExportExcel(ByVal dgvSouse As DataGridView, ByVal blnIsOnlyVisible As Boolean)
        '尝试执行导出操作，出现异常则抛出.
        Try
            Dim IntColumnNumHead As Integer '定义表头循环的列数.
            Dim IntRowNumText As Integer '定义内容循环的行数.
            Dim IntColumnNumText As Integer '定义内容循环的列数.
            Dim IntCurrentRow As Integer '定义当前的列.
            Dim IntCurrentCol As Integer '定义当前的行.
            Dim Excel As Excel.Application = New Excel.Application '定义Excel程序.
            Excel.Application.Workbooks.Add(True) '增加一个Excel.
            IntCurrentCol = 1 '记录当前的列数.
            '循环将表头填入Excel
            For IntColumnNumHead = 0 To dgvSouse.ColumnCount - 1
                '判断用户是否添加所有的内容.
                If blnIsOnlyVisible Then
                    '如果用户只添加可见内容则判断哪些列不可见.
                    If dgvSouse.Columns(IntColumnNumHead).Visible Then
                        '只添加可见的列.
                        Excel.Cells(1, IntCurrentCol) = dgvSouse.Columns(IntColumnNumHead).HeaderText
                        IntCurrentCol = IntCurrentCol + 1
                    End If
                Else
                    '如果用户添加所有内容则全部添加.
                    Excel.Cells(1, IntColumnNumHead + 1) = dgvSouse.Columns(IntColumnNumHead).HeaderText
                End If
            Next
            IntCurrentRow = 2 '记录当前的行数.
            '循环将内容填入Excel中.
            For IntRowNumText = 0 To dgvSouse.RowCount - 1
                IntCurrentCol = 1
                For IntColumnNumText = 0 To dgvSouse.ColumnCount - 1
                    '判断用户是否添加所有的内容.
                    If blnIsOnlyVisible Then
                        '如果用户只添加可见内容则判断哪些列不可见.
                        If dgvSouse.Columns(IntColumnNumText).Visible Then
                            '只添加可见的列.
                            Excel.Cells(IntRowNumText + 2, IntCurrentCol) = dgvSouse.Rows(IntRowNumText).Cells(IntColumnNumText).Value
                            IntCurrentCol = IntCurrentCol + 1
                        End If
                    Else
                        '如果用户添加所有内容则全部添加.
                        Excel.Cells(IntRowNumText + 2, IntColumnNumText + 1) = dgvSouse.Rows(IntRowNumText).Cells(IntColumnNumText).Value
                    End If
                Next
            Next
            Excel.Visible = True '将Excel设为可见.
        Catch ex As Exception
            Throw New Exception("导出失败") '抛出异常.
        End Try
    End Sub

从此写代码不再是为了运行（不值一提）更是为了让后来者（包括自己）阅读！

附：微软编码规范检查工具StyleCop

注：雏，幼小的（多指鸟类）；雏，鸡子也。——《说文》（摘自百度百科）