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

淡淡的烟草味﹌ 2022-06-09 02:06 195阅读 0赞

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

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

![1342459170_8157.jpg][]

**命名 (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这样的单字母变量用作小的循环变量。
 *  如果使用匈牙利命名法，定义一个明确的标准前缀列表，以方便项目中的开发者使用。欲了解更多信息，请参阅“[匈牙利表示法][Link 1]”
 *  可以为变量名增加一个符号来标识作用域，如前缀**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.)
 *  在整个程序中，使用统一的风格，用一致的标点和结构来添加注释。

[MSDN-Coding Techniques and Programming Practices]: http://msdn.microsoft.com/en-us/library/aa260844%28v=vs.60%29.aspx
[1342459170_8157.jpg]: https://img-my.csdn.net/uploads/201207/17/1342459170_8157.jpg
[Link 1]: http://msdn.microsoft.com/en-us/library/aa260976%28v=vs.60%29.aspx