开发规范

Notion原文

命名规范

1、命名空间

• 规则

  1. 使用Pascal规则，且首字符大写
  2. 尽量反映其内容所提供的的整体功能
  3. 存在版本号时放在命名空间名称结尾，以“V”开头，如：V2_1_1
  4. 按项目代号.框架层.模块1…模块n.<版本号>顺序

• 例

  namespace JW.Buss.Interface.Content.Artical.Entities.V2_7 {
      /// <summary>
      ///
      /// </summary>
      public class ArticalEntity {
      }
  }

2、类

• 规则

  1. 使用Pascal规则命名类名，首字母大写
  2. 使用能够反映类功能的名词或名词短语命名类
  3. 不要使用“I”、“C”、“_”等特点含义前
  4. 文件名要能反映类的内容，最好是和类同名
  5. 自定义异常类应以“Exception”结尾
  6. 自定义特性应以“Attribute”结尾
  7. 数据实体应以“Entity”结尾
  8. 数据映射/输出应以“Dto”结尾
  9. AutoMapper映射规则类应以“Profile”结尾

• 例

  public class Test {}
  public class TestEntity {}
  public class TestAttribute {}
  public class TestExecption {}
  public class TestDto {}
  public class TestProfile

3、类字段（类成员）

• 规则

  1. 使用Camel规则命名，即首单词（或单词缩写）小写。
  2. 类字段前可加“_”前缀
  3. 禁止在普通变量前加“m_”（VC老命名规则）

• 例

  public class Test {
  	private string name;
  	private string _name;
  	private string myFavorite;
  }

4、属性

• 规则

  1. 使用名词定义属性
  2. 使用Pascal规则

• 例

  public class Test {
  	public string Name { get; set; }
  }

5、常量

• 规则

  1. 只读常量使用Pascal命名规则
  2. 枚举名使用Pascal命名规则
  3. 枚举值从小到大顺序定义
  4. 静态字段或属性才有Pascal

• 例

  public class Test {
  	public const string Name = "JW.Quartz.Message.User";
  	private readonly double Pi = 3.14159365753
  }

6、参数

• 规则

  1. 采用camel命名规则
  2. 使用描述性参数名称，参数名称应当具有最够的说明性
  3. 检查方法所有输入参数的有效性

• 例

  public class Test {
  	public void Get(string name,string favorite) {
  	
  	}
  }

7、接口

• 规则

  1. 采用Pascal规则，且必须以大写“I”开头
  2. 接口名称要有意义，中间不能有下划线“_”等字符
  3. 如果类实现了接口，名称尽量和接口相同，只是省掉“I”字符

• 例

  public interface ITest {}
  interface IExample {}

8、方法

• 规则

  1. 采用Pascal命名规则
  2. 方法名应使用动词或动词短语
  3. 异步方法名应以“Async”结尾
  4. 类中访问修饰符或功能相同的方法应该放在一起，且公共或实现接口的方法在前

• 例

  public class Test {
  	public void Create(string name,string favorite) {}
  	public Task CreateAsync(string name,string favorite) {}
  	private void Get() {}
  }

9、事件

• 规则

  1. 委托名称采用Pascal命名规则
  2. 定义事件的委托要是用EventHandle后缀，且包括sender和e两个参数
  3. 事件用到的参数，名称要带有“EnentArgs”后缀

• 例

  public delegate void DoTask();
  public class Test {
  	public event DoTask DoTaskEventHandle(Object sender,EventArgs e) {}
  	public event DoTask DoTaskEventHandle2(string strEventArgs) {}
  }

10、路由

• 规则

  1. 采用Pascal命名规则
  2. 路由层级必须“api/[controller]/[模块1]…./[模块n]/[名词]/[动词]/[路由参数]”
  3. 动词可省略

• 例

  [Route("api/[controller]")]
  public class TestController {
  	[HttpPost("Example/Create")]
  	public Task<IActionResult> CreateAsync(TestEntity entity) {}
  	[HttpGet("Example/{id}")]
  	// [HttpGet("Example")]
  	public Task<IActionResult> GetExampleById(int id) {}
  }

11、业务多版本并存

• 规则

  1. 使用版本文件夹，第一个版本可不使用
  2. 命名空间以版本结尾
  3. 多版本的类名、接口名等都相同
  4. 一般情况下不存在不同版本之间的混合引用，存在以命名空间区分

• 例

  // 默认，1.0
  // 文件夹：Test
  namespace JW.Buss.Interface.Test {
  	public interface ITestService {}
  }
  // 文件夹：Test
  namespace JW.Buss.Service.Test {
  	public class TestService : ITestService {}
  }
  // 文件夹：Controller/Test
  namespace Api.Test {
  	using JW.Buss.Interface.Test;
  	[Route("api/[controller]")]
  	// [ApiVersion("1.0")]
  	public class TestController {
  		private readonly ITestService _testService;
  		public TestController(ITestService testService) {
  			_testService= testService;
  		}
  	}
  }
  
  // 2.0
  // 文件夹：Test/V2.0
  namespace JW.Buss.Interface.Test.V2_0 {
  	public interface ITestService {}
  }
  // 文件夹：Test/V2.0
  namespace JW.Buss.Service.Test.V2_0 {
  	using JW.Buss.Interface.Test.V2_0;
  	// public class TestService : Interface.Test.V2_0.ITestService {}
  	public class TestService : ITestService {}
  }
  // 文件夹：Controller/Test/V2.0
  namespace Api.Test.V2_0 {
  	using JW.Buss.Interface.Test.V2_0;
  	[Route("api/[controller]")]
  	[ApiVersion("2.0")]
  	public class TestController {
  		private readonly ITestService _testService;
  		// private readonly Buss.Interface.Test.V2_0.ITestService _test;
  		public TestController(ITestService testService) {
  		// public TestController(Buss.Interface.Test.V2_0.ITestServicetestService) {
  			_testService= testService;
  		}
  	}
  }

注释规范

1、文件头部注释

• 规则
  1. 文件都包含文件头，要说明文件名、作者、创建时间、变更记录

2、类、属性、函数体注释

• 规则
  1. 使用“///”三斜线注释
  2. 应尽量说明问题

3、缩写规范

• 规则
  1. 标识符应当直观可望文知意，不提倡使用任何缩写
  2. 字符串变量推荐是用“str”或“s”开头，采用string.Empty来初始化。
  3. 普通对象可以以“obj”开头。
  4. 缩写可自行定义，一般取单词的前/后字符组成，以含义直观为准则。
  5. 一般情况下不要让缩写破坏标识符的含义。

4、排版

• 规则
  1. 每行语句至少占一行，如果语句过长（超过一屏），应不超过100字符，则该语句断为两行显示。
  2. 把相似的内容放在一起，比如字段、属性、方法、事件等，使用“#region–#endregion”命令分组。
  3. 多个程序元素进行对等操作时， 操作符之前、之后或者前后都要加空格。
  4. 每个方法的源程序行数原则上应该少于200行。(如果超过过多，则需要另写一方法)
  5. 语句嵌套层次不得超过3层。
  6. 避免相同的代码段在多个地方出现。(尽量避免代码重复，能复用则复用)
  7. 函数与函数之间的空行必须1行

5、语句结构

• 规则
  1. 如果使用了异常结构，一定要处理异常， 一般是要写日志文件。
  2. 分支语句不应该使用复杂长条件， 应该将长条件封装成方法。
  3. switch语句，case后面必须接break或者return
  4. 禁止使用goto语句进行跳转。
  5. 行文中严禁出现“魔数”，特定含义的常数必须定义成枚举或常量。
  6. 不同类型的操作符混合使用时，使用括号给出优先级。
  7. 不允许使用复杂的操作符组合等。
  8. 循环、判断语句的程序块部分用花括号括起来， 即使只有一条语句。
  9. 在switch语句中总是要有default字句，建议使用断言。
  10. 每个类和方法完成单一的功能，不设计多用途面面俱到的类或方法。
  11. 严禁使用未经初始化的变量，变量通常使用构造方法来初始。

6、代码缩进

• 规则

  1. 不允许使用Java中的括号换行规范

  2. 使用4个空格来表示缩进

  3. 花括号

     1. 类的自动属性花括号与代码合占一行，例public string Name {get;set;}
     2. 左花括号 “{” 放于关键字或方法名同一行

     public class Test {
     	public static void Main(string[] args) {
     		if(valid) {
     				// if valid
     		} else {
     				// not valid
     		}
     		
     		while(1){
     				// do something
     		}
     	}
     }

7、大小写

• 规则
  1. 不要创建名称相同，但大小写区别的任何元素。
  2. 应当大写仅有两个字符的缩写。(如果只有两个字符，则都大写)
  3. 不要把易混淆的数字和字符放在一起。
  4. 使用英文命名标识符。

8、重名规范

• 规则
  1. 不允许变量名、类名、属性名、 方法名等与系统标识符重名

9、SQL编码规范

• 规则
  1. SQL语句全部大写
  2. 对较为复杂的SQL语句加上注释，说明其功能。
  3. 连接符OR、IN、AND、以及=、<=、>=等前后加空格。
  4. 使用明确的列代替 SELECT *。
  5. 表名必须以“t_”开头
  6. 视图必须以“v_”开头

10、软件架构

• 规则
  1. 数据库中每一张表对应一个实体类（Entity）
  2. 实体类名称使用表名，必须带有Entity后缀。
  3. 数据传输对象，必须带有Dto后缀
  4. 服务接口，必须带有Service后缀

附表

表1 各种类型命名规范

表2 数据类型缩规范