编码工艺Coding Techniques)-命名和注释

转载请注明出处:http://blog.csdn.net/horkychen

(节选自MSDN-Coding Techniques and Programming Practices)

命名 (Names)

命名最有利于了解程序的逻辑结构。一个名字说明是"什么(what)”比说明"如何(how)"更重要。通过命名可以避免暴露底层的实现，从而保留一个抽象层，简化了程序的复杂性。例如，你可以使用GetNextStudent()代替GetNextArrayElement()。

一个命名的宗旨是，命名应当基于它的目的进行推敲。名称必须简洁且意义明确。对编程(programmatically)而言，命名就是为了易于区分彼此。表达准确的名称便于阅读，也便于看代码的人理解。不过具体的命名方式仍受限于所用的语言和遵循的标准。

以下是推荐的命名技巧:

例程(Routines, 过程或函数)

• 避免可能被误解的名称，多为主观性的名词，如 Analyze()函数，或变量 xxK8。这样的名字存在歧义。
• 在面向对象的语言，类的属性名称中不需要包含类的名称。如 Book.BookTitle。可以使用 Book.Title代替。
• 使用动词 - 名词(动宾)的结构为方法命名, 如 CalculateInvoiceTotal()。
• 在允许函数重载的语言中，所有重载应该执行类似的功能。对于那些不允许函数重载的语言中，为相似功能的函数建立一个命名标准。

变量(Variables)

• 如果需要，在变量名后追加计算限定符（Avg，Sum，Min，Max，Index）。
• 在变量名中成对使用反义词，如min/max, begin/end, and open/close，以及get/set等等。
• 由几个单词连接的变量名称，使用大小写混合的格式，以简化它们。此外，为了帮助区分变量和例程(函数,routine)，例程名称使用Pascal命名法，所有单词的首字母都为大写(CalculateInvoiceTotal)。变量名则使用驼峰命名法(Camel casing)(如documentFormatType)，除第一个单词首字母小写外其余每个单词除首字母全部大写。
• 布尔变量名称应当有是/否或真/假的意味，如 fileIsFound.
• 在命名状态变量时，避免使用Flag。相对于布尔值，它们可能有两个以上的值。相对于documentFlag，可以使用一个更具描述性的名称，如documentFormatType。
• 即使只在几行代码中出现的一个临时变量，也尽量使用有意义的名称。只把i,j这样的单字母变量用作小的循环变量。
• 如果使用匈牙利命名法，定义一个明确的标准前缀列表，以方便项目中的开发者使用。欲了解更多信息，请参阅“匈牙利表示法”
• 可以为变量名增加一个符号来标识作用域，如前缀g_的全局变量和m_的模块/类成员变量。
• 常量应该全部大写，且在单词间用下划线隔开。如NUM_DAYS_IN_WEEK。对于枚举变量，应当有一个共同的前缀。如FONT_ARIAL或FONT_ROMAN。

数据表(Tables)

• 命名表(tables)时，以单数形式命名。例如，应当使用Employee，而不是Employees。
• 表中的列命名时，不要重复的表的名称，例如，避免在名为Employee的表中定义字段EmployeeLastName。
• 不要在列的命名中包含数据类型。日后变更数据类型时，这样就可以简化工作。

其它(Miscellaneous)

• 少使用缩写。如果使用了，就必须要保持一致。缩写应该只有一个意思，同样，相应的词汇也应该只有一个缩写。例如，如果使用min代表最小化，那就不要让它表示分钟(minute)的缩写。
• 当命名函数时，可以包含对返回值的描述。如GetCurrentWindowName()。
• 文件和文件夹的名称，就像程序名称一样，应准确描述他们所服务的目的是什么。
• 避免不同类型的元素使用相似的名称，如称为ProcessSales()函数和变量iProcessSales。
• 避免同音字命名以方便Code review，如write和right。
• 元素命名时，应避免使用常常拼写错误的单词。当然也要了解美式英语和英式英语中一些单词的差异，如color/colour (都是颜色) and check/cheque(都是支票)。
• 避免使用打印符号标识数据类型。如使用$代表字串或者%代表整数。

注释(Comments)

软件文档存在两种形式：外部和内部。外部文档在源代码之外，如规范，帮助文件和设计文件。内部文档则在源代码中，是由开发人员在开发时写的注释组成。

最大的挑战就是如何确保注释能与源代码同步更新。尽管正确注释源代码不会左右程序运行，但对于维护特别复杂或繁琐的软件，它却是无价的。

以下是推荐的注释技巧：

• 修改代码时，同步更新注释。
• 在每个方法或函数的开始，提供标准的注释模板(如Doxygen注释)，以指示例程的目的，假设和限制。注释模板应该是一个简单的介绍，了解方法或函数的目的和功能。
• 避免代码行的末尾添加注释，它会使代码更难阅读。不过，可以在变量声明后添加注释。在这种情况下，可以使用制表符对齐所有行注释。
• 避免自定义的注释集合(clutter comments)方法，如整行的星号。可以使用空格区隔代码和注释。
• 避免在注释块周围包上打印符号(typographical frame, $,#,%之类的)。可能你觉得会比较好看，但却很难维护。
• 在正式发布之前，移除所有临时或无关的注释，以避免影响日后的维护工作。
• 如果你需要注释一段复杂的代码，应当先检查，看看能不能重写(重构)。尽量不要注释糟糕的代码，而应当重构它。必须在性能和可维护性之间寻求平衡。
• 注释要使用完整的句子，它的目的是澄清代码，而不是再生歧义。
• 及时注释你的代码，因为以后更没时间去做。此外，趁热打铁的过一遍代码会比6周会再做更为有效。
• 不要有多余的注释，如幽默的旁白或对公司的控诉。
• 使用注释来解释代码的意图，而不是代码的翻译。
• 注释任何代码中比较隐晦的部分。
• 为了防止问题重复出现，给bug修复和解决方案的代码加上注释。 这对于团队尤为重要。
• 为包含循环和逻辑分支的代码添加注释。这些是有助于读者阅读代码的关键位置。
• 使用空格分隔注释，可以有突出的作用，更易于定位。(Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.)
• 在整个程序中，使用统一的风格，用一致的标点和结构来添加注释。