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

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

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

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

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