|
发表于 2008-3-27 21:51:28
|
显示全部楼层
代码注释约定
正常来说注释是不会编译到exe里面去的,程序一般都提倡加注释,程序的后期维护工作很重,注释起了很关键的作用
看看MSDN对注释的解释:
- [b]代码注释约定[/b]
- 所有的过程和函数都应该以描述这段过程的功能的一段简明注释开始(这段例程干什么)。这种描述不应该包括执行过程细节(它是怎么做的),因为这常常是随时间而变的,而且这种描述会导致不必要的注释维护工作,甚至更糟--成为错误的注释。代码本身和必要的嵌入注释将描述实现方法。
- 当参数的功能不明显且当过程希望参数在一个特定的范围内时,也应描述传递给过程的参数。被过程改变的函数返回值和全局变量,特别是通过引用参数的那些,也必须在每个过程的起始处描述它们。
- 过程头注释块应该包括下列节标题。关于例子,请参阅下节“格式化代码”。
- 节标题 注释描述
- 目的 该过程完成什么(而不是怎么完成)。
- 假设 列出每个外部变量、控件、打开文件或其它不明显元素。
- 效果 列出每个被影响的外部变量、控件、或文件及其作用(只有当它不明显时)。
- 输入 每一个可能不明显的参数。参数分别在单独的行上,并嵌入注释。
- 返回 函数返回值的说明。
- 记住下列几点:
- 每一个重要变量的声明应该包括一个嵌入注释,来描述该变量的使用。
- 变量、控件及过程的命名应该足够清楚,使得只有复杂的执行细节才需要嵌入注释。
- .Bas 模块包含工程的 Visual Basic 一般常量声明,在其起始处,应该包括描述应用程序的综述,列举主要数据对象、过程、算法、对话、数据库及系统需求。有时,一段描述算法的伪码可能会有所帮助。
- 格式化代码
- 因为许多程序员仍然使用 VGA 显示器,所以在允许代码格式来反映逻辑结构和嵌套的同时,应尽可能地省屏幕空间。下面列出几点:
- 标准的、基于制表位的嵌套块应该被缩进四个空格(缺省情况下)。
- 过程的功能综述注释应该缩进一个空格。跟在综述注释后面的最高级的语句应该缩进一个制表位,而每一个嵌套的块再缩进一个制表位。例如:
- '*****************************************************
- '目的: 在用户列表数组中找出
- ' 一个指定用户的第一次出现位置。
- '输入:
- ' strUserList(): 被搜索的用户列表。
- ' strTargetUser: 要搜索的用户名。
- ' 返回: 在rasUserList 数组中rsTargetUser
- ' 的第一次出现的索引。
- ' 如果目标用户没找到,返回-1。
- '*****************************************************
- Function intFindUser (strUserList() As String, strTargetUser As _
- String)As Integer
- Dim i As Integer ' 循环计数器。
- Dim blnFound As Integer ' 目标寻找标志。
- intFindUser = -1
- i = 0
- While i <= Ubound(strUserList) and Not blnFound
- If strUserList(i) = strTargetUser Then
- blnFound = True
- intFindUser = i
- End If
- Wend
- End Function
复制代码
所有的过程和函数都应该以描述这段过程的功能的一段简明注释开始(这段例程干什么)。
可见微软对写注释的重视程度及其作用! |
|