前言
之前工作中整理的一篇编码规范。
代码注释
注释约定
只在需要的地方加注释，不要为显而易见的代码加注释
使用///生成的xml标签格式的文档注释
方法注释
所有的方法都应该以描述这段代码的功能的一段简明注释开始（方法是干什么）。这种描述不应该包括执行过程细节（它是怎么做的）
/// <summary> /// 把对象类型转化为指定类型 /// </summary> /// <typeparam name="T">动态类型 </typeparam> /// <param name="value">要转化的源对象 </param> /// <returns> 转化后的指定类型的对象，转化失败引发异常。</returns> public static T CastTo<T>(this object value)
代码行注释
如果某一功能需要多行代码，并有多个逻辑结构，应在此代码前添加注释，说明此块代码的处理思路及注意事项等
注释从新行增加，与代码开始处左对齐
注释双斜线与注释之间以空格分开，示例如下：
1 public void Dispose(){ 2 // 如果连接已打开，则关闭连接并释放资源 3 if(this.connection.State == ConnectionState.Open ){ 4 this.connection.Close(); 5 this.connection.Dispose(); 6 } 7 }
变量注释
变量需添加注释，说明变量的用途
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