dotNET Core：编码规范

在项目开发过程中，由于时间紧、任务重，很容易导致面向功能编程。实现相同的功能，代码可以写的很优雅，也可以写的很晦涩和复杂。现在的工作，都需要进行团队协作，代码就需要有一定的规范进行指引，因为我们需要写出让人可以轻易读懂的代码，而不仅仅是机器。

规范没有绝对的标准，遵循大部分人都认可的一种方式就可以了，保持统一。比如在 dotNET Core 中，我们可以参考下 dotNET Core 的源码，最终制定一个适合团队的规范即可。

下面是我理解的正确的一些规范：

基本准则

1、命名的规范分为两种：Pascal（大驼峰）和驼峰（小驼峰），示例如下:

• Pascal：UserName
• 驼峰：userName

2、命名要有意义，需要看到名称知其含义。少用拼音和匈牙利命名法。

示例
Int price=20;	√
UserInfo userInfo=GetUserInfo(userId);	√
Int p=20;	×
Int intPrice=20;	×

3、对于类的成员变量，用this关键字，增强代码可读性。
4、对于基类的成员变量，用base关键字，增强代码可读性。

名称规范

好的名称可以让我们减少很多不必要的注释，可以让代码阅读者很容易就理解代码的意思。但命名不是一件容易的事情，在命名的时候，通常伴随着我们对代码逻辑的思考。比如：如果你不能给一个函数很准确地命名，那可能这个函数的职责不单一，做的事情太多，才导致一个名称很难概括，意味着代码可能需要重构。好的命名是我们写好代码的基础。

命名空间

命名空间采用Pascal命名法：

1 2	namespace Fw.Application{} namespace Fw.SmartFlow.Acitivity{}

实际工作中，我们会将很多逻辑上属于同一类的文件，在物理上分成不同的目录，这时建议修改命名空间为相同的命名空间。

类

类采用Pascal命名法：

1	public class UserService{}

类是对属性和方法的封装，类有很多的种类：

跟数据库表对应的实体类
处理业务逻辑的业务类
提供扩展方法的扩展类
接口层的数据传输类

不同的种类可以约定俗成地进行一些名称的约束，比如扩展类用 Extension 结尾、接口层的使用 Request、Response 结尾，等等，这样在阅读代码是就知道什么类型的职责是什么。

接口

接口采用大写I+Pascal命名法：

1	public interface IUserService{}

方法

方法采用Passcal命名法：

1	public string GetUserName(){}

方法的命名需要比较具体，越抽象的名称越难以理解。例如，InitData() 就是一个不太好的名称，改成 InitConfiginfo() 会更好些。另外，方法的命名在同一类型的语义下要保持一致，在一些项目中看到查找类的方法，有 GetXXX、QueryXXX、FindXXX 等等。五花八门的方式会提升阅读的成本。

变量

变量分为：类变量、静态类变量、只读变量、静态只读变量、方法变量。

类变量：

1	private string _userName;

类变量只能使用 private 修饰符，如果需要暴漏出去，或是给子类使用，使用属性来进行封装。

静态类变量、只读变量、静态只读变量：

1 2	private static readonly ResourceManager _resourceManager; public static readonly IRouter Instance = new MockRouter();

• 修饰符为 private: _ + 驼峰命名法；
• 修饰符为 public: Pascal 命名法；
• 修饰符为 protected：Pascal 命名法；

方法变量：

1	bool isCheck;

常量：

常量采用Pascal命名法：

1	public const string AuthorizationFilter = "Authorization Filter";

属性：

属性采用 Pascal 命名法：

1	public BasicApiContext DbContext { get; }

参数

参数采用驼峰命名法：

1	public List<BizApp> GetBizAppList(string userId,DeviceType deviceType)

注释规范

注释是一把双刃剑，当代码中存在大量的注释的时候，我们第一反应会先看注释，并会默认注释中写的内容是对的，真实情况是注释往往会给我们错误的指导。有两个原因：

当代码逻辑放生变化时，只修改了代码，注释没有调整；
不同的人员都对注释进行编辑，慢慢注释会变得和代码不匹配。

Martin Fowler 在他的经典书籍《重构》中也提到过多的注释是一种坏味道的体现，他认为，当你觉得需要写注释的时候，应该先想想是不是可以进行重构。那是不是程序中就不应该出现注释呢？当然不是，我认为下几种情况是需要写注释的：

时间紧急，临时写的一些 ”烂代码“，需要写注释，说明原因，一般需要加上 TODO ；
复杂算法类的方法，可以写注释说明逻辑；
写的是偏底层的类库，对外暴露的方法需要写注释，调用方能方便在智能提示中显示；
如果你的能力写不好代码，那还是先把注释写上吧。

异常规范

异常的目的是用来报告错误，这也是他的唯一目的，所以避免在返回值中来返回错误信息，所有的地方都应该使用抛异常的方式来报告错误；
使用抛异常的方式可以防止错误的操作继续执行；
要能够预估到会出现什么异常，知道是什么类型的异常，才 Try 住做相关的处理；
最终用户友好和对开发者友好；
暴漏问题比隐藏问题要好，隐藏问题只会导致更严重的问题。

详细的异常处理可以参考之前的文章：

dotNET：怎样处理程序中的异常（理论篇）？
dotNET：怎样处理程序中的异常（实战篇）？

空行规范

空行规范是一个很简单的规范，就是在每个方法中，代码应该按照不同逻辑的逻辑块进行分割显示，虽然简单，但如果不注意，还是会对代码的阅读带来很大的障碍。下面看看 dotNET Core 的源码 CreateDefaultBuilder 方法：

public static IHostBuilder CreateDefaultBuilder(string[] args)
{
    var builder = new HostBuilder();

    builder.UseContentRoot(Directory.GetCurrentDirectory());
    builder.ConfigureHostConfiguration(config =>
    {
        config.AddEnvironmentVariables(prefix: "DOTNET_");
        if (args != null)
        {
            config.AddCommandLine(args);
        }
    });

    builder.ConfigureAppConfiguration((hostingContext, config) =>
    {
        var env = hostingContext.HostingEnvironment;

        config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
              .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);

        if (env.IsDevelopment() && !string.IsNullOrEmpty(env.ApplicationName))
        {
            var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));
            if (appAssembly != null)
            {
                config.AddUserSecrets(appAssembly, optional: true);
            }
        }

        config.AddEnvironmentVariables();

        if (args != null)
        {
            config.AddCommandLine(args);
        }
    })
    .UseDefaultServiceProvider((context, options) =>
    {
        var isDevelopment = context.HostingEnvironment.IsDevelopment();
        options.ValidateScopes = isDevelopment;
        options.ValidateOnBuild = isDevelopment;
    });

    return builder;
}