代码编程规则

 

高质量的代码示例往往具有如下特质:

　　1. 易懂-代码示例必须易读且简单明确。它们必须能展示出重点所在。示例代码的相关部分应当易于重要。示例代码不可包含多余代码。它们必须带有相应的稳定说明。

　　2. 正确性 – 示例代码必须正确展示出其欲告知使用者的重点。代码必须经过测试，且可以按照文档描述进行编译和运行。

 

　　3. 一致性 – 示例代码应该按照一致的编程风格和设计来保证代码易读。 同样的，不同代码示例之间也应当保持一致的风格和设计，使使用者能够很轻松的结合使用它们。一致性将我们一站式示例代码库优良的品质形象传递给使用者，展示出我们对于细节的追求。

 

　　4. 流行性 – 代码示例应当展示现行的编程实践，例如使用 Unicode，错误处理，防御式编程以及可移植性。示例代码应当使用当前推荐的运行时库和API函数，以及推荐的项目和生成设置。

 

　　5. 可靠性 – 代码示例必须符合法律，隐私和政策标准和规范。不允许展示入侵性或低质的编程实践，不允许永久改变机器状态。所有的安装和执行过程必须可以被撤销。

 

　　6. 安全性 -  示例代码应该展示如何使用安全的编程实践 ：例如最低权限原则，使用运行时库函数的安全版本，以及SDL推荐的项目设置。

 

　　7.一定不要 -在一个源文件内拥有一个以上的Public类型。除非它们只有范型参数个是的差别。或者具有嵌套关系。一个文件内有多个内部类型是允许的（一个源文件内只能有一个public类型。其余的用protected。private）

 

　　8.一定请- 以源文件所含的Public类名命名该文件。比如， MainForm 类应该在 MainForm.cs 文件内，而 List<T> 类应该在 List.cs 文件内

 

　　9. 一定请 -为各种类型，函数，变量，特性和数据结构选取有意义的命名。其命名应能反映其作用

 

　　10.您不应该 -在标识符名中使用缩短或缩略形式的词。比如，使用 “GetWindow” 而不是 “GetWin”。对于公共类型，线程过程，窗口过程，和对话框过程函数，为“ThreadProc”, “DialogProc”, “WndProc” 等使用公共后缀。

 

　　11.一定不要- 使用下划线，连字号，或其他任何非字母数字的字符。

 

　　

标识符	规范	命名结构	示例
类，结构体	Pascal规范	名词	public class ComplexNumber {...} public struct ComplextStruct {...}
命名空间	Pascal规范	名词 ý 一定不要 以相同的名称来命名命名空间和其内部的类型。	namespace Microsoft.Sample.Windows7
枚举	Pascal规范	名词 þ 一定请 以复数名词或名词短语来命名标志枚举，以单数名词或名词短语来命名简单枚举。	[Flags] public enum ConsoleModifiers  { Alt, Control }
方法	Pascal规范	动词或动词短语	public void Print（） {...} public void ProcessItem（） {...}
Public属性	Pascal规范	名词或形容词 þ 一定请 以集合中项目的复数形式命名该集合，或者单数名词后面跟 “List” 或者 “Collection”。 þ 一定请 以肯定短语来命名布尔属性， （CanSeek ，而不是CantSeek）。当以 “Is,” “Can,” or “Has” 作布尔属性的前缀有意义时，您也可以这样做。	public string CustomerName public ItemCollection Items public bool CanRead
非Public属性	Camel规范或_camel规范	名词或形容词  þ一定请 在您使用'_' 前缀时，保持代码一致性。	private string name; private string _name;
事件	Pascal规范	动词或动词短语  þ 一定请 用现在式或过去式来表明事件之前或是之后的概念。  ý  一定不要 使用 “Before” 或者“After” 前缀或后缀来指明事件的先后。	// A close event that is raised after the window is closed.  public event WindowClosed   // A close event that is raised before a window is closed. public event WindowClosing
委托	Pascal规范	þ 一定请 为用于事件的委托增加‘EventHandler’ 后缀。  þ 一定请 为除了用于事件处理程序之外的委托增加 ‘Callback’后缀。  ý  一定不要 为委托增加  “Delegate” 后缀。	public delegate WindowClosedEventHandler
接口	Pascal规范，带有‘I’ 前缀	名词	public interface IDictionary
常量	Pascal规范用于Public常量；  Camel规范用于Internal常量; 只有1或2个字符的缩写需全部字符大写。	名词	public const string MessageText = "A"; private const string messageText = "B"; public const double PI = 3.14159...;
参数，变量	Camel规范	名词	int customerID;
泛型参数	Pascal规范，带有‘T’ 前缀	名词 þ 一定请 以描述性名称命名泛型参数，除非单字符名称已有足够描述性。 þ 一定请 以T作为描述性类型参数的前缀。 þ 您应该 使用 T 作为单字符类型参数的名称。	T, TItem, TPolicy
资源	Pascal规范	名词 þ 一定请 提供描述性强的标识符。同时，尽可能保持简洁，但是不应该因空间而牺牲可读性。 þ 一定请 仅为命名资源 使用字母数字字符和下划线。	ArgumentExceptionInvalidName

 

一定不要 使用  ‘+’ 操作符 （ VB.NET中的‘&’） 来拼接大量字符串。相反，您应该使用StringBuilder 来实现拼接工作。然而，拼接少量的字符串时，一定请使用 ‘+’ 操作符（ VB.NET中的‘&’） 。

 

Good: 

StringBuilder sbXML = new StringBuilder（）;

sbXML.Append（"<parent>"）;

sbXML.Append（"<child>"）;

sbXML.Append（"Data"）;

sbXML.Append（"</child>"）;

sbXML.Append（"</parent>"）;

 

 一定请 使用 String.Equals 的重载版本来测试2个字符串是否相等。 比如，忽略大小写后，判断2个字符串是否相等，

　　if （str1.Equals（str2, StringComparison.OrdinalIgnoreCase））

　　If （str1.Equals（str2, StringComparison.OrdinalIgnoreCase）） Then

 

一定不要 使用 String.Compare 或CompareTo 的重载版本来检验返回值是否为0，来判断字符串是否相等。 这2个函数是用于字符串排序，而非检查相等性。

 

 

一定请 在字符串比较时，以String.ToUpperInvariant函数使字符串规范化，而不用String.ToLowerInvariant

 

一定请- 使用继承来表示 “is a” 关系，例如 “猫是一种动物”。

 

一定请-使用 接口，例如IDisposable，来表示 “can do” 关系，例如 “对象能被释放”。