编码规范

编码规范

编码规范

C# 编码风格指南

一旦进入代码开发阶段，你必须安排好代码审查计划以确保每个人都遵守同样的规则。建议按以下3种方式进行代码审查：

  1. 互相审查 - 由其他团队成员进行代码审查以确保遵守了代码规范且达到要求。这种方式可以配合单元测试。项目中每个代码文件必须要通过这个程序。

  2. 架构审查 - 架构人员需对项目核心模块进行审查以确保符合设计，没有出现大的甚至有可能影响整个项目运转的纰漏。

  3. 团队审查 - 每周随机选择一个或多个文件进行一次团队审查。审查会议开始前30分钟，将文件打印并分发到每个成员手里，会议开始后用投影仪将文件内容展示出来。代码的每一块都要进行审查，让所有成员提出改进建议。（别忘了要感谢提供素材的开发人员，并确保他不会觉得受到了“群嘲”！）

代码文件组织

C# 源代码文件

每个源代码文件应该只包含一个类定义，也即类定义只出现在它自己的文件中。源代码文件名需与类声明里的类名保持一致。
譬如一个名为User的类的源文件名应该是User.cs。

版权声明

1
2
3
4
5
6
7
8
9
10
11
//-------------------------------------------------------------------------------
// Copyright (c) Dick. All Right Reserved. 
// This source is subject to the Microsoft Permissive License. 
// Please see the License.txt file for more information. 
// All other rights reserved. 
// 
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
// PARTICULAR PURPOSE. 
//-------------------------------------------------------------------------------

目录设计

每层命名空间都要建立目录（以MyProject.UI.Admin为例，请使用MyProject/UI/Admin这样的目录结构，而不是只建立一层名为MyProject.UI.Admin的目录）。

代码排列

C#源代码文件整体顺序应为：

1
2
3
Using 声明
Namespace声明
Class 和 interface 声明

C#类内部分的顺序应为：

1
2
3
4
5
成员变量
属性
构造函数
方法
`

以上每个部分都需要放到 #region里。

命名空间和USING声明

  1. Using 和命名空间声明都要左边界齐平。
  2. 命名空间的每个组件名首字母要大写
  3. 如果组件名是个缩写，只让第一个字母大写，如 System.Data.Sql。
  4. 如果这个缩写只有2个字母，那可以2个字母都大写，如 System.IO。

注意: 移除不需要的或重复的命名空间，使用短的命名空间来代替。譬如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Preferred
using System.Data.SqlClient;
public void ValidationCall(){  
… 
SqlConnection conn = new SqlConnection(connstr);
…
}

// Avoid
public void ValidationCall(){  
… 
System.Data.SqlClient.SqlConnection conn = new SqlConnection(connstr);
…
}

创建和修订记录

文件创建和修订记录需要按以下格式填写到using代码段后面，namespace之前。

1
2
3
4
5
/*
* 作者:                创建日期:
* 修订者：             修订日期：               修订内容：
* 
*/

XML 文档

Visual Studio提供了一种文档类型，在开发环境中可以用来检测并导出到结构化的XML中，以用来创建与源代码分离的代码级别的文档。
XML 文档用于描述类、方法和属性。它应当在所有可用的情况下尽可能使用。

缩进

空行

适当的空行能增强代码可读性。它们能帮助区分逻辑不相干的代码片段。
双行空行要放在：
源代码中逻辑不相关的代码片段之间
不同的类和接口定义（如果有时候不得不放在同个文件，尽量避免这种情况）
单行空行要放在：

  • 方法与方法之间
  • 属性与属性之间
  • 方法体内的局部变量和它的第一次使用之间
  • 方法体内不同逻辑片段之间以增强可读性

换行

如果一个表达式在一行内放不下，则根据以下常用原则来进行换行：

  1. 操作符号之后换行
  2. 逗号之后换行
  3. 择较高等的换行，其次才是较低等的换行 （譬如优先对括号外的部分换行）
    换行后需要缩进
    ：
    1
    2
    3
    4
    5
    6
    7
    // 调用方法
    SomeMethod1(expression1, expression2, expression3, expression4, expression5);
    // 声明方法
    void SomeMethod1(long Expression1, long Expression2, long Expression3,                 long Expression4, long Expression5)
    {     
        //...
    }

注意: 换行后第二行的缩进与第一个参数齐平
以下是一个数学表达式换行的例子。第一种换行方式是较好的，因为是在括号以外的地方进行的换行，也即是在较高等进行的分行。

1
2
3
4
5
// Preferred
var1 = var2 * (var3 + var4 – var5) + 
       var4 * var6;
// Avoid
var1 = var2 * (var3 + var4 - var5) + var4 * var6;

对if表达式的分行需要使用缩进：

1
2
3
4
if ((condition1 && condition2) || (condition3 && condition4) && condition5 || !condition6)
{	
    ...
}

三元表达式请用这两种格式：

1
2
3
4
Alpha = aLongBooleanExpression ? beta : gamma;
Alpha = aLongBooleanExpression ?
        beta : 
        gamma;

代码间距

空格间距

在代码中间的逗号或分号后应该有单独的一个空格，此外一个关键字与后跟的括号之间也要有个空格，譬如：

1
2
3
4
5
6
7
8
9
10
// Correct
TestMethod(a, b, c);
while (condition)
{
    //... 
}

// Avoid
TestMethod(a, b, c);
TestMethod(a, b, c);

注意: 在方法名和它的前括号之间不需要有空格。这样便于区分是关键字还是方法名。
操作符两边要加上空格（++或逻辑非这样的一元运算符除外），譬如：

1
2
3
4
5
6
7
a = b; // Avoid a=b;

// Avoid for(int i=0; i<10; ++i) or for(int i=0;i<10;++i)
for (int i = 0; i < 10; ++i)
{
    ...
}

TAB间距

该使用几个空格作为代码缩进距离从来没有达成一致过。有人喜欢2个空格，有人喜欢4个而有人喜欢8个甚至更多。所以最好使用Tab缩进。它的好处有：
可以自定义缩进距离
它只需一个字符，所以只要按一次键而不是2,4,8…

如果你要增加缩进（或减少）一片代码，可以选中它们然后按Tab来增加或者Shift+Tab来减少缩进。几乎所有文本编辑器都支持这个操作。
在这里Tab指的就是标准的缩进字符。
注意： 不要使用空格来缩进代码-用Tab！在VS中把Tab配置成4个空格的距离。

一般注释

通用注释前缀

TODO : 表示以后别忘了在这里还需要进一步处理
BUG: [bugid]：表示这里有个已知bug，解释一下bug情况，如果可以则给出bug id。
KLUDGE: 表示这里的代码有点糟糕，解释一下有时间的话将如何改进。
TRICKY: 表示以下代码比较奇技淫巧，如果没有仔细思考请不要改动。
WARNING: 表示当心某事
COMPILER: 表示临时注释掉某些影响编译通过的代码。这些问题最终会被解决的。
ATTRIBUTE: value：嵌在注释中的属性的一般形式。你可以自定义属性，它们最终会被VS提取。

单行注释

1
2
//Console.WriteLine("哈哈");
//Console.ReadKey();

多行注释

1
2
3
4
/*
 * 注释内容
 * 注释内容
 */

文档注释

1
2
3
4
/// <summary>
/// 文档注释
/// 文档注释
/// </summary>

变量声明及命名规范

变量：

Camel：变量名首单词的首字母小写，其余每个单词首字母单词大写,多用于给变量或字段或方法参数命名。　　

1
2
3
var str = "123";
var highSchoolStudent = "123";
int num = 5;

常量：

1
public static const string BaseIpAddress = "";

方法名：

Pascal：每个单词的首字母都要大些其余小写，多用于类或方法。尽量用一般名词或动名词。

1
2
3
4
public string GetHighSchoolStudent()
{
    
}

动态属性ExpandoObject

NET

#动态属性ExpandoObject

动态对象 ExpandoObject中添加动态属性？

1
2
3
4
5
6
7
8
dynamic obj = new ExpandoObject();
IDictionary<string, object> temp = new Dictionary<string, object>();
temp.Add(Key, Value);

foreach (KeyValuePair<string, object> item in temp)
{
    ((IDictionary<string, object>)obj).Add(item.Key, item.Value);
}

因为不难发现ExpandObject继承自以下接口：
IDictionary<string, object>, ICollection<KeyValuePair<string, object>>, IEnumerable<KeyValuePair<string, object>>, IEnumerable

编码规范

NET

编码规范

C# 编码风格指南

一旦进入代码开发阶段，你必须安排好代码审查计划以确保每个人都遵守同样的规则。建议按以下3种方式进行代码审查：

  1. 互相审查 - 由其他团队成员进行代码审查以确保遵守了代码规范且达到要求。这种方式可以配合单元测试。项目中每个代码文件必须要通过这个程序。

  2. 架构审查 - 架构人员需对项目核心模块进行审查以确保符合设计，没有出现大的甚至有可能影响整个项目运转的纰漏。

  3. 团队审查 - 每周随机选择一个或多个文件进行一次团队审查。审查会议开始前30分钟，将文件打印并分发到每个成员手里，会议开始后用投影仪将文件内容展示出来。代码的每一块都要进行审查，让所有成员提出改进建议。（别忘了要感谢提供素材的开发人员，并确保他不会觉得受到了“群嘲”！）

代码文件组织

C# 源代码文件

每个源代码文件应该只包含一个类定义，也即类定义只出现在它自己的文件中。源代码文件名需与类声明里的类名保持一致。
譬如一个名为User的类的源文件名应该是User.cs。

版权声明

1
2
3
4
5
6
7
8
9
10
11
//-------------------------------------------------------------------------------
// Copyright (c) dick. All Right Reserved. 
// This source is subject to the Microsoft Permissive License. 
// Please see the License.txt file for more information. 
// All other rights reserved. 
// 
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
// PARTICULAR PURPOSE. 
//-------------------------------------------------------------------------------

目录设计

每层命名空间都要建立目录（以MyProject.UI.Admin为例，请使用MyProject/UI/Admin这样的目录结构，而不是只建立一层名为MyProject.UI.Admin的目录）。

代码排列

C#源代码文件整体顺序应为：

1
2
3
Using 声明
Namespace声明
Class 和 interface 声明

C#类内部分的顺序应为：

1
2
3
4
5
成员变量
属性
构造函数
方法
`

以上每个部分都需要放到 #region里。

命名空间和USING声明

  1. Using 和命名空间声明都要左边界齐平。
  2. 命名空间的每个组件名首字母要大写
  3. 如果组件名是个缩写，只让第一个字母大写，如 System.Data.Sql。
  4. 如果这个缩写只有2个字母，那可以2个字母都大写，如 System.IO。

注意: 移除不需要的或重复的命名空间，使用短的命名空间来代替。譬如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Preferred
using System.Data.SqlClient;
public void ValidationCall(){  
… 
SqlConnection conn = new SqlConnection(connstr);
…
}

// Avoid
public void ValidationCall(){  
… 
System.Data.SqlClient.SqlConnection conn = new SqlConnection(connstr);
…
}

创建和修订记录

文件创建和修订记录需要按以下格式填写到using代码段后面，namespace之前。

1
2
3
4
5
/*
* 作者:                创建日期:
* 修订者：             修订日期：               修订内容：
* 
*/

XML 文档

Visual Studio提供了一种文档类型，在开发环境中可以用来检测并导出到结构化的XML中，以用来创建与源代码分离的代码级别的文档。
XML 文档用于描述类、方法和属性。它应当在所有可用的情况下尽可能使用。

缩进

空行

适当的空行能增强代码可读性。它们能帮助区分逻辑不相干的代码片段。
双行空行要放在：
源代码中逻辑不相关的代码片段之间
不同的类和接口定义（如果有时候不得不放在同个文件，尽量避免这种情况）
单行空行要放在：

  • 方法与方法之间
  • 属性与属性之间
  • 方法体内的局部变量和它的第一次使用之间
  • 方法体内不同逻辑片段之间以增强可读性

换行

如果一个表达式在一行内放不下，则根据以下常用原则来进行换行：

  1. 操作符号之后换行
  2. 逗号之后换行
  3. 择较高等的换行，其次才是较低等的换行 （譬如优先对括号外的部分换行）
    换行后需要缩进
    ：
    1
    2
    3
    4
    5
    6
    7
    // 调用方法
    SomeMethod1(expression1, expression2, expression3, expression4, expression5);
    // 声明方法
    void SomeMethod1(long Expression1, long Expression2, long Expression3,                 long Expression4, long Expression5)
    {     
        //...
    }

注意: 换行后第二行的缩进与第一个参数齐平
以下是一个数学表达式换行的例子。第一种换行方式是较好的，因为是在括号以外的地方进行的换行，也即是在较高等进行的分行。

1
2
3
4
5
// Preferred
var1 = var2 * (var3 + var4 – var5) + 
       var4 * var6;
// Avoid
var1 = var2 * (var3 + var4 - var5) + var4 * var6;

对if表达式的分行需要使用缩进：

1
2
3
4
if ((condition1 && condition2) || (condition3 && condition4) && condition5 || !condition6)
{	
    ...
}

三元表达式请用这两种格式：

1
2
3
4
Alpha = aLongBooleanExpression ? beta : gamma;
Alpha = aLongBooleanExpression ?
        beta : 
        gamma;

代码间距

空格间距

在代码中间的逗号或分号后应该有单独的一个空格，此外一个关键字与后跟的括号之间也要有个空格，譬如：

1
2
3
4
5
6
7
8
9
10
// Correct
TestMethod(a, b, c);
while (condition)
{
    //... 
}

// Avoid
TestMethod(a, b, c);
TestMethod(a, b, c);

注意: 在方法名和它的前括号之间不需要有空格。这样便于区分是关键字还是方法名。
操作符两边要加上空格（++或逻辑非这样的一元运算符除外），譬如：

1
2
3
4
5
6
7
a = b; // Avoid a=b;

// Avoid for(int i=0; i<10; ++i) or for(int i=0;i<10;++i)
for (int i = 0; i < 10; ++i)
{
    ...
}

TAB间距

该使用几个空格作为代码缩进距离从来没有达成一致过。有人喜欢2个空格，有人喜欢4个而有人喜欢8个甚至更多。所以最好使用Tab缩进。它的好处有：
可以自定义缩进距离
它只需一个字符，所以只要按一次键而不是2,4,8…

如果你要增加缩进（或减少）一片代码，可以选中它们然后按Tab来增加或者Shift+Tab来减少缩进。几乎所有文本编辑器都支持这个操作。
在这里Tab指的就是标准的缩进字符。
注意： 不要使用空格来缩进代码-用Tab！在VS中把Tab配置成4个空格的距离。

一般注释

通用注释前缀

TODO : 表示以后别忘了在这里还需要进一步处理
BUG: [bugid]：表示这里有个已知bug，解释一下bug情况，如果可以则给出bug id。
KLUDGE: 表示这里的代码有点糟糕，解释一下有时间的话将如何改进。
TRICKY: 表示以下代码比较奇技淫巧，如果没有仔细思考请不要改动。
WARNING: 表示当心某事
COMPILER: 表示临时注释掉某些影响编译通过的代码。这些问题最终会被解决的。
ATTRIBUTE: value：嵌在注释中的属性的一般形式。你可以自定义属性，它们最终会被VS提取。

单行注释

1
2
//Console.WriteLine("哈哈");
//Console.ReadKey();

多行注释

1
2
3
4
/*
 * 注释内容
 * 注释内容
 */

文档注释

1
2
3
4
/// <summary>
/// 文档注释
/// 文档注释
/// </summary>

变量声明及命名规范

变量：

Camel：变量名首单词的首字母小写，其余每个单词首字母单词大写,多用于给变量或字段或方法参数命名。　　

1
2
3
var str = "123";
var highSchoolStudent = "123";
int num = 5;

常量：

1
public static const string BaseIpAddress = "";

方法名：

Pascal：每个单词的首字母都要大些其余小写，多用于类或方法。尽量用一般名词或动名词。

1
2
3
4
public string GetHighSchoolStudent()
{
    
}