C#格式规范

前言

之前工作中整理的一篇编码规范。

代码注释

注释约定

只在需要的地方加注释，不要为显而易见的代码加注释

使用 /// 生成的xml标签格式的文档注释

方法注释

所有的方法都应该以描述这段代码的功能的一段简明注释开始（方法是干什么）。这种描述不应该包括执行过程细节（它是怎么做的）

/// <summary>
/// 把对象类型转化为指定类型
/// </summary>
/// <typeparam name="T">动态类型 </typeparam>
/// <param name="value">要转化的源对象 </param>
/// <returns> 转化后的指定类型的对象，转化失败引发异常。</returns>
public static T CastTo<T>(this object value)

代码行注释

如果某一功能需要多行代码，并有多个逻辑结构，应在此代码前添加注释，说明此块代码的处理思路及注意事项等

注释从新行增加，与代码开始处左对齐

注释双斜线与注释之间以空格分开，示例如下：

public void Dispose(){
	// 如果连接已打开，则关闭连接并释放资源
	if(this.connection.State == ConnectionState.Open ){
		this.connection.Close();
		this.connection.Dispose();
	}
}

变量注释

变量需添加注释，说明变量的用途

Class级变量使用 /// 生成的Xml标签格式的文档注释

/// <summary>
/// 文档名称
/// </summary>
public static string docName = "";

方法级的变量注释可以放在变量声明语句后，与上下行的注释左对齐，注释与代码间以 Tab 键分隔

public void CreateDoc() {
    string docType = "";                   //文档类型
    string author = "";                    //作者
    DateTime createDate = DateTime.Now;    //创建世界
}

命名规范

命名基本约定

PascalCasing：

包含一个或多个单词，每个单词首字母大写，其余小写

使用范围：命名空间、类、接口、方法、属性、事件、非私有字段、枚举值

namespace System.IO
public static class Console
public enum FileAccess

camelCasing：

包含一个或多个单词，第一个单词首字母小写，其余单词首字母大写

使用范围：方法参数、局部变量

public string GetName(int productId){
	string productName = null;
}

_camelCasing：

"_"+camelCasing的方式

使用范围：私有字段

private string _productName;

UPPER_CAPS：

包含多个单词，每个单词的所有字母大写，单词之间使用"_"连接

使用范围：const常量

public const string DEFAULT_NAME = "default";

示例：

namespace ConsoleApp {
	public delegate void SalesOutEventHandler();

	public class Product {
		public event SalesOutEventHandler OnSalesOut;

		public Product GetProductById(int productId) {
			return null;
		}

		private enum ProductType {
		}
	}
}

标识符命名约定

类和接口

类的名字使用名词

避免使用单词缩写，除非是广为人知的，比如： HTTP , IO

接口以 I 字母开头

同一项目不同命名空间中的类，命名避免重复

方法

第一个单词为动词

返回值为 bool 类型，则加 Is , Can , Try前缀

变量

尽量使用短而有意义的单词

单字符变量名一般用于生命周期非常短的变量，如 for , foreach 中递增变量可以被命名为 i

如果变量表示集合，则变量名使用复数，如 RowsCount

命名控件使用匈牙利命名法，前缀遵循同一个缩写表

在带单位的值变量后加“_camelCasing”格式的单位，如： public void CreateCache(int cacheSize_mb)

类型成员排列顺序

类型成员的排列顺序自上而下依次为：

字段： 私有字段、受保护字段

属性： 私有属性、受保护属性、公有属性

事件： 私有事件、受保护事件、公有事件

构造函数： 参数数量最少的构造函数，参数数量中等的构造函数，参数数量最多的构造函数

方法： 重载方法的排列顺序与构造函数相同，从参数数量最少往下至参数最多

其他规范

代码长度

每行代码不宜过长，应在屏幕宽度之内，约为80-120个字符左右。换行规则如下：

在逗号后换行

在操作符后换行

在高层换行而不是在低层换行

换行后与上一行语句对齐

推荐写法：

var n = a * b / (c - g + f) +
		4 * z;

不推荐写法：

var n = a * b / (c - g +
	f) + 4 * z;

方法行数

每个方法的有效代码行数（不包括注释和空行）应保持在50行以内

空白

空行是为了将逻辑相关的代码分块，以便提高阅读性

在以下情况使用两个空行：

类声明和接口声明之间

两个类声明之间

枚举与类声明之间

在以下情况使用一个空行：

方法与方法、属性与属性之间

方法中变量声明与语句之间

方法与方法之间

方法不同逻辑块之间

类中属性与方法、属性与字段、方法与字段之间

注释与它注释的语句之间不空行，与其他语句之间空一行

在以下情况使用空格：

在VS编辑器中可以使用快捷键格式化代码

参数列表的逗号后，void UpdateDate(int a, int b)

二元操作符，a += b - c;

强制类型转换后，c = (char) a;

代码缩进

代码缩进使用Tab键，不要使用空格，Tab键的宽度为4个字符，VS中设置如下：

【工具】-【选项】-【文本编辑器】-【C#】-【制表符】，选中【保留制表符】

代码半展开

把花括号放在前一条语句的末尾，VS中设置如下：

【工具】-【选项】-【文本编辑器】-【C#】-【格式设置】-【新行】，取消右侧所有勾选

附录

注释内容

项目	注释内容
类	类的目的，开发历史
接口	接口的目的，如何使用
字段/属性	字段描述
方法注释	方法作用，返回值，抛出的异常，调用的前提和后置条件
方法内部注释	控制结构，复杂的代码，处理顺序
参数	用来做什么，约束，前提条件
局部变量	用处，目的

XML文档注释

MSDN文档注释标签 https://msdn.microsoft.com/zh-cn/library/5ast78ax(v=vs.140).aspx

标记	说明
<c>	提供了一种将说明中的文本标记为代码的方法
<code>	提供了一种将多行指示为代码的方法
<example>	可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到<code>标记的使用。
<exception>	对可从当前编译环境中获取的异常的引用。
<include>	引用描述源代码中类型和成员的另一文件中的注释。
<list>	用于定义表或定义列表中的标题行。
<para>	用于诸如<summary>、<remarks> 或 <returns> 等标记内，使您将结构添加到文本中。
<param>	应当用于方法声明的注释中，以描述方法的一个参数。
<paramref>	提供了一种指示词为参数的方法。
<permission>	将成员的访问记入文档。
<remarks>	用于添加有关某个类型的信息，从而补充由 <summary> 所指定的信息。
<returns>	应当用于方法声明的注释，以描述返回值。
<see>	从文本内指定链接。
<seealso>	对可以通过当前编译环境进行调用的成员或字段的引用。
<summary>	应当用于描述类型或类型成员。
<value>	描述属性。

VS常用快捷键

功能	VS2010	VS2013	说明
文档格式化	Ctrl+E, Ctrl+D	Ctrl+K, Ctrl+D	格式化当前文档
选定内容格式化	Ctrl+E, Ctrl+F	Ctrl+K, Ctrl+F	格式化选中内容
注释	Ctrl+E, Ctrl+C	Ctrl+K, Ctrl+C	注释当前行
取消注释	Ctrl+E, Ctrl+U	Ctrl+K, Ctrl+U	取消注释当前行
复制	Ctrl+C	-	复制光标所在行，不需要选中
剪切	Ctrl+X	-	剪切光标所在行，不需要选中
删除	Ctrl+L	-	删除光标所在行，不需要选中
折叠	-	Ctrl+M, Ctrl+O	折叠当前文档
展开折叠	-	Ctrl+M, Ctrl+L	展开当前文档

参考

MSDN开发语言和工具 https://msdn.microsoft.com/zh-cn/library/aa187916.aspx

C#语言规范 C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC#\Specifications\2052\CSharp Language Specification.docx