风格指南

Providers/
  CatLib.LoginUI/
    ButtonLogin.cs
    ButtonRegister.cs
    CheckboxAgreement.cs
    InputText.cs
    InputPassword.cs

因为编辑器通常会按字母顺序组织文件，所以将高级别的单词排在前类之间的重要关系一目了然。

(B)多级目录与类命名

(B)函数名和类名大小写

在声明函数和类的时候，其命名始终使用CamelCase。

我们遵循了微软提供的框架设计指南来确保 API 的一致性和易用性。

错误的例子

public class fileSystem
{
}

正确的例子

public class FileSystem
{
}

(B)将接口绑定到服务，而不是为服务设定别名

我们强烈建议将接口绑定到服务，而不是为服务设定别名。如果以别名的形式设定，很多事件将会无法使用，如：Watch。

错误的例子

App.Bind<FileSystem>().Alias<IFileSystem>();

错误点：直接使用了别名，而没有对实现进行绑定主要接口。

正确的例子

App.Bind<IFileSystem>(()=> new FileSystem());

App.Bind<IFileSystem, FileSystem>();

App.Bind<IFileSystem, FileSystem>().Alias<IDisk>();

如果存在多个接口需要指向一个服务，请使用别名功能。

(B)服务内的命名规范一致

对于一个服务中的命名规范强烈建议一致，例如：要么变量是_开头要么始终是m_开头（或者其他统一的规范，如：无标示符开头）。而不能交叉混用。

交叉混用会导致团队一致性下降，从而提高理解成本。单个组件一般由2-3人协同开发。我们强烈建议以服务为最小单元统一代码命名规范。

错误的例子

• Providers/CatLib.FileSystem/FileSystem.cs

public class FileSystem
{
    private string defaultDiskName;
    private IDictionary<string, IDisk> m_disks;
}

• Providers/CatLib.FileSystem/Disk.cs

public class Disk
{
    private string _diskName;
}

正确的例子

• Providers/CatLib.FileSystem/FileSystem.cs

public class FileSystem
{
    private string defaultDiskName;
    private IDictionary<string, IDisk> disks;
}

• Providers/CatLib.FileSystem/Disk.cs

public class Disk
{
    private string diskName;
}

(C)使用上下文关系来处理不同实例相同接口的服务

我们建议使用上下文关系来处理不同实例相同接口的服务，而不是使用在具体实现构造函数中通过获取指定服务。如果在实际的实现中获取服务实例，将会和框架耦合，并产生公共耦合。

而将这些关系定义在服务提供者中将会避免这些问题。

错误的例子

public class GameVideo : IGameVideo
{
    public GameVideo(IFileSystem fileSystem)
    {
        var disk = fileSystem.Get("oss");
    }
}

正确的例子

public class GameVideo : IGameVideo
{
    public GameVideo(IDisk disk)
    {
    }
}

App.Singleton<IGameVideo, GameVideo>()
    .Needs<IDisk>()
    .Given(()=> App.Make<IFileSystem>().Get("oss"));

(C)总是在服务提供者中来注册服务

我们建议服务在服务提供者中进行绑定，而不是在Register以外的其他地方。

错误的例子

• 在Register之外的其他地方

protected override void OnStartCompleted()
{
    App.Singleton<IFileSystem, FileSystem>();
}

正确的例子

public class ProviderFileSystem : ServiceProvider
{
    public override void Register()
    {
        App.Singleton<IFileSystem, FileSystem>();
    }
}

(C)字符串常量的值，可以映射到实际类型

我们建议字符串常量，可以映射到实际有效的类型或者该常量本身。这样在未来需要通过常量值来分析时可以快速定位具体的类。

错误的例子

public class ApplicationEvents 
{
    public const string Bootstrapping = "bootstrapping";
}

正确的例子

public class ApplicationEvents 
{
    public const string Bootstrapping = "ApplicationEvents.Bootstrapping";
}

(C)一个服务只提供一个服务提供者

一个服务只提供一个服务提供者。如果一个服务提供了多个服务提供者将会导致沟通成本的上升，使用者无法了解不同服务提供者之间的区别或不知道该如何使用。

我们建议使用变量控制的方式来处理这个问题。

错误的例子

• Providers/CatLib.FileSystem/ProviderFileSystemClean.cs

public class ProviderFileSystemClean : ServiceProvider
{
    public override void Register()
    {
        App.Singleton<IFileSystem, FileSystem>();
    }
}

• Providers/CatLib.FileSystem/ProviderFileSystem.cs

public class ProviderFileSystem : ServiceProvider
{
    public override void Register()
    {
        App.Singleton<IFileSystem, FileSystem>()
            .OnResolving((instance) =>
            {
                var fileSystem = (FileSystem)instance;
                fileSystem.Extend(()=> new Disk(new AdapterLocal()), "local");
                fileSystem.Extend(()=> new Disk(new AdapterHttp()), "http");
            });
    }
}

正确的例子

• Providers/CatLib.FileSystem/ProviderFileSystem.cs

public class ProviderFileSystem : ServiceProvider
{
    public bool ExtendDefaultAdapter { get; set; } = false;
    public override void Register()
    {
        var binder = App.Singleton<IFileSystem, FileSystem>();
        if(!ExtendDefaultAdapter)
        {
            return;
        }
        binder.OnResolving((instance) =>
        {
            var fileSystem = (FileSystem)instance;
            fileSystem.Extend(()=> new Disk(new AdapterLocal()), "local");
            fileSystem.Extend(()=> new Disk(new AdapterHttp()), "http");
        });
    }
}

(C) 避免使用 protected 变量

关系密切的概念应该互相靠近，否则就会导致在某个类中进行摸索，一个函数跳到另外一个函数，上下求索，弄清这些函数如何操作，如何互相关系，或是了解变量与函数的继承链条，所以除非有很好的理由，否则就不要把关系密切的概念放到不同的文件之中，这也是我们不建议使用protected变量的原因，因为它会破坏这一关系。

错误的例子

public class Foo
{
    protected string foo;
}

正确的例子

public class Foo
{
    private string foo;
}

(C)可拆分单词的命名

有些时候我们可能纠结于可拆分单词如何进行命名，如：username可以被拆分为user和name。虽然这些单词可以被拆分但是我们需要注意username为英文中的一个整体单词。所以我们应该视作为一个单词。

错误的例子

public class LoginUI
{
    private string userName; // UserName, _userName 都是错误的例子
}

正确的例子

public class LoginUI
{
    private string username; // Username, _username 都是正确的例子
}

(C)门面应该放置在Facades命名空间下

属于门面的代码应该被放置在项目名.Facades的命名空间下。

错误的例子

• Providers/CatLib.FileSystem/Facades/FileSystem.cs

namespace CatLib.FileSystem
{
    public class FileSystem : Facade<IFileSystem>
    {
    }
}

正确的例子

• Providers/CatLib.FileSystem/Facades/FileSystem.cs

namespace CatLib.Facades
{
    public class FileSystem : Facade<IFileSystem>
    {
    }
}

门面作为一个特殊存在，所以我们允许其命名空间例外于其他规范。

(C)对外提供的接口总是放在API文件夹下

我们建议对外提供服务的接口放在Providers/API/组件名文件夹下，这样可以达成接口即文档的意义。

内部使用的接口可以直接放在组件实现的文件夹中，而无需放在API文件夹下。

错误的例子

- Providers/
- - FileSystem/
- - - API/
- - - - IFileSystem.cs
- - - - IDisk.cs
- - - FileSystem.cs
- - - ProviderFileSystem.cs
- - Debugger/
- - - API/
- - - - IDebugger.cs
- - - Debugger.cs
- - - ProviderDebugger.cs

- Providers/
- - API/
- - - FileSystem/
- - - - IFileSystem.cs
- - - - IDisk.cs
- - - Debugger/
- - - - IDebugger.cs
- - FileSystem/
- - - FileSystem.cs
- - - ProviderFileSystem.cs
- - Debugger/
- - - Debugger.cs
- - - ProviderDebugger.cs

foreach (var index in new int[1, 2, 3, 4, 5])
{
    closure(()=> index); // index 为预期外的值
}

foreach (var index in new int[1, 2, 3, 4, 5])
{
    var localIndex = index;
    closure(()=> localIndex);
}

public virtual void GenericMethod<T1,T2>(T1 data) // 一旦虚函数被覆盖(override)并调用会引发AOT异常
{
}

public void GenericMethod<T1,T2>(T1 data)
{
}