编写易读的代码

成功的开发团队要求队伍中的每一位成员遵守代码重用规则，这些规定把代码的重用性推到极至同时却不会显著降低开发人员的创造力和开发效率。如果编写和使用代码的开发人员遵守共同的程序命名规范代码和代码注释要求，那么代码的重用性就会得以大大提升。这些标准的起点是系统结构级的。你的功能规范应该在类、属性的名字、函数返回值以及其他关键程序元素的定义中反映这些标准。本文将就基本的命名规则和注释提出一些可行的建议，意图帮助读者开发自己的代码重用标准。


大小写标准


在我们开始讨论各类程序要素命名的正确方式之前，先让我们定义区分元素的字符大小写的两种最常用方式，它们是：

Pascal规范—第1个字符大写，目标名中的每个单词的第1个字母也大写，比如InvoiceNumber或者PrintInvoice。其他的所有字符都小写。
Camel规范—第1个字符不大写，但目标名中的每个单词的第1个字母大写，比如，invoiceNumber。其他的所有字符都小写。
可是，采用字符大小写区分元素可能在对大小写不敏感的编程语言中引发问题。比方说，由于C#语言区分大小写，所以你可以调用私有变量employee，接着它所具有的公共属性Employee则可以被调用者所用。这些操作是完全合法的。但是，对Visual Basic来说就会产生错误，因为VB是不区分字母大小写的，以上两种元素在VB看来都是一回事。假如你在混合语言环境下工作，你只能指定某些规则要求开发人员合理利用多种语言阅读其他人开发的代码。


命名标准
假设我们采用了以上的大小写标准，现在就让我们了解一些通用程序元素的简单命名建议。

类
某些类设计为模拟真实世界的对象，就这些类来说，所选用的名字就应该反映真实世界的对象、具有单数名词的格式，比方Employee、 Invoice或者Timecard等。对内部类而言可以采用Pascal规范令结果类具有单数形式的名字，比如ThreadPool或者CustomColor等。类应当是单数的，这样它们的复数形式就可以代表同类的集合名，比如Employees数组等。

类的成员
采用C#以及其他大小写敏感编程语言的开发人员应当采用camel规范命名类成员的名字。这样做可以让开发者更易于区分内部变量的名字（name）和公共属性的名字（Name）。许多VB开发人员更喜欢采用匈牙利命名法为类成员起名，也就是在名字前面加上前缀表示变量的类型，比如sName就指的是string类型的Name变量。我认为，在使用VS.NET这样高级的开发环境下这样做是不必要的，因为在这种情况下系统鼠标停留在变量之上即可可自动显示变量的类型。我个人喜欢在类成员名前加上前缀：小写的字母m。这样内部变量就保存了足够的内部类信息：内部变量mName就正好代表了公共属性Name。

方法
方法应该用Pascal规范命名，同时用合理的方式说明他们的实施行为。比方说，给数据库添加雇员的方法可以命名为AddEmployee，而打印发票的方法则不妨命名为PrintInvoice。假如方法返回的是布尔值，那么方法名应该以动词开头以便用在if语句的时候其含义更明显。比如说，假如你有一个方法的功能是确定某位雇员是否符合公司401k计划的要求，那么你可以在If语句中调用IsEligible401k方法：If IsEligible401k then…

方法参数、返回值和变量
所有的方法参数、返回值和变量都应该采用Pascal规范命名，同方法名一样也应该能反映参数或者变量所代表的含义。这一点对参数方法而言特别重要，因为你在调用方法的时候智能感知（Intellisense）会返回参数名和参数类型。所有采用方法的开发人员都应该使用描述性的名字和类型，便于相互理解其含义。

控件
控件命名是开发领域一个经常引发争议的问题。虽然大多数人赞同不应该使用控件的默认名称，比如TextBox1或者Label1等等，但是，他们还反对按照变量的方式命名控件或者采用前缀表示控件的类型。我比较喜欢采用标准的三字母前缀命名窗体中控件的名字。比如说，保存姓氏和名字的文本框控件就不妨分别命名为txtLastName和txtFirstName。处理窗体数据的命令按钮则可以命名为cmdSubmit或者cmdCancel。其实，只要你能保证控件命名的一致性而且标准易于理解即可。

注释
注释代码对所有开发人员来说都是必要的。为了教授正确的注释技术，我就经常在自己的演示程序中添加注释代码。同时，为了简化注释过程，我建议开发人员首先编写注释说明他们想编写的程序。我首先会写注释说明程序中的过程、类或者其他程序要素，但对其具体工作原理不做阐述。然后我会编写一系列的注释代码描述过程的每一主要步骤或者类的元素。在编写了定义类或者说明过程的代码之后，我对各个外部变量、控件、打开的文件乃至其他过程所访问的元素文档化，对输入参数和返回值做简要说明。

如果你在使用C#开发程序，那么VS.NET环境已具有内置的工具帮助你把内部C# 注释转换为外部HTML文档。你可以在自己的文档中加上特殊的处理指示符而改变外部文档的表示方式。有关这方面的更多信息可以参考VS.NET内部帮助文件： ms-help://MS.VSCC/MS.MSDNVS/csref/html/vcoriXMLDocumentation.htm.

原文转自：http://www.ltesting.net