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

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

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

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

l  写注释太费时间

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

l  有些过程很难注释。

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

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

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

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

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

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

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

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

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

l  内部注释方面：

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

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

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

修改后的代码

   1:      ''' <summary>

   2:      ''' 将DataGridview中的数据导出到Excel

   3:      ''' <summary>

   4:      ''' <param name="dgvSouse">要导出到Excel的DataGridView<param>

   5:      ''' <param name="blnIsOnlyVisible">判断是否添加所有DataGridView中的内容<param>

   6:      ''' <remarks><remarks>

   7:      Sub ExportExcel(ByVal dgvSouse As DataGridView, ByVal blnIsOnlyVisible As Boolean)

   8:          '尝试执行导出操作，出现异常则抛出.

   9:          Try

  10:              Dim IntColumnNumHead As Integer '定义表头循环的列数.

  11:              Dim IntRowNumText As Integer '定义内容循环的行数.

  12:              Dim IntColumnNumText As Integer '定义内容循环的列数.

  13:              Dim IntCurrentRow As Integer '定义当前的列.

  14:              Dim IntCurrentCol As Integer '定义当前的行.

  15:              Dim Excel As Excel.Application = New Excel.Application '定义Excel程序.

  16:              Excel.Application.Workbooks.Add(True) '增加一个Excel.

  17:              IntCurrentCol = 1 '记录当前的列数.

  18:              '循环将表头填入Excel

  19:              For IntColumnNumHead = 0 To dgvSouse.ColumnCount - 1

  20:                  '判断用户是否添加所有的内容.

  21:                  If blnIsOnlyVisible Then

  22:                      '如果用户只添加可见内容则判断哪些列不可见.

  23:                      If dgvSouse.Columns(IntColumnNumHead).Visible Then

  24:                          '只添加可见的列.

  25:                          Excel.Cells(1, IntCurrentCol) = dgvSouse.Columns(IntColumnNumHead).HeaderText

  26:                          IntCurrentCol = IntCurrentCol + 1

  27:                      End If

  28:                  Else

  29:                      '如果用户添加所有内容则全部添加.

  30:                      Excel.Cells(1, IntColumnNumHead + 1) = dgvSouse.Columns(IntColumnNumHead).HeaderText

  31:                  End If

  32:              Next

  33:              IntCurrentRow = 2 '记录当前的行数.

  34:              '循环将内容填入Excel中.

  35:              For IntRowNumText = 0 To dgvSouse.RowCount - 1

  36:                  IntCurrentCol = 1

  37:                  For IntColumnNumText = 0 To dgvSouse.ColumnCount - 1

  38:                      '判断用户是否添加所有的内容.

  39:                      If blnIsOnlyVisible Then

  40:                          '如果用户只添加可见内容则判断哪些列不可见.

  41:                          If dgvSouse.Columns(IntColumnNumText).Visible Then

  42:                              '只添加可见的列.

  43:                              Excel.Cells(IntRowNumText + 2, IntCurrentCol) = dgvSouse.Rows(IntRowNumText).Cells(IntColumnNumText).Value

  44:                              IntCurrentCol = IntCurrentCol + 1

  45:                          End If

  46:                      Else

  47:                          '如果用户添加所有内容则全部添加.

  48:                          Excel.Cells(IntRowNumText + 2, IntColumnNumText + 1) = dgvSouse.Rows(IntRowNumText).Cells(IntColumnNumText).Value

  49:                      End If

  50:                  Next

  51:              Next

  52:              Excel.Visible = True '将Excel设为可见.

  53:          Catch ex As Exception

  54:              Throw New Exception("导出失败") '抛出异常.

  55:          End Try

  56:      End Sub

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

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

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