开发者指南

本篇文档适用于对 EToD Engine (易创物理引擎) 进行开发的引擎客户端研发工程师。

开发守则

以下规则适用于所有使用 EToD Engine 引擎代码库进行迭代开发的引擎工程师。我们对所有开发者做出以下要求的目的是，我们希望为每一位开发者提供更加便捷的协同开发的开发环境，帮助引擎开发者和使用引擎创作的制作人生产出更高质量的产品，并且我们希望尽可能地保持我们代码本身具有较高质量的可读性。因此我们列出了以下开发要求：

作为一个数字孪生方向的物理引擎，我们自然地将 EToD Engine 划分为许多不同的离散系统，我们希望这些不同的系统可以很好地协同工作。通常，我们希望这些不同的系统将拥有相对应的 所有者 - 负责特定系统或代码部分的引擎工程师。他们通常（但不总是）是对应系统的原始作者，但是某些系统也可能存在多个所有者。通常，所有权会隐含在编写代码的工程师身上，也就是说，引擎工程师会自动成为他们编写的代码的所有者 (对于他们设计和实现的系统尤其如此) ，因此我们相信每一位引擎工程师的著作权将得到保证。当然，总会有例外，但这些工作属于我们负责引擎项目技术总监的责任。每一位引擎工程师所做出的贡献我们会在引擎中特别注明，并在我们的引擎官网中特别鸣谢。

代码所有制，即所有者需要对自己所拥有的代码负责。每当引擎工程师需要进入 非自己所有的 代码系统部分时，并确定需要修改该部分代码时，我们认为遵循该部分的开发规则与系统框架是非常重要的。这些需要遵守的规则可以概括为以下几点：

除非有重要原因，否则 不要修改 不属于您所拥有的任何代码（例如，‎您需要扩展某些系统功能，以适配来自您正在开发的新的功能的程序接口‎）。在没有得到系统所属的代码所有者的技术支持前，不要随意更改其系统中的任何代码，因为不论 任何代码 发生更改，都有可能会出现您甚至想象不到的程序错误提醒或是引擎的断言信息 - 因为您很有可能从来没有编写过该部分的系统代码！

如果您所开发的系统中确实需要对其他系统中的部分代码进行更改， 请联系该部分系统的所有者并清楚的说明你的功能需求 。这一点非常重要，因为该部分系统所负责的代码所有者比您更了解代码 (及其代码逻辑、"load-bearing" 属性等)，这种协作可以确保您所编辑的所有代码均是正确的，并将代码编辑后可能产生错误的概率降至最低。通过这样协作来完成，我们可以保证原系统代码的所有者，可以第一时间了解到自己所负责的系统中的代码的变更，以方便整个引擎更高的开发效率。

如果 EToD Engine 中的某个系统出现了严重的错误 - 即使您不是该系统的所有人，请联系我们的引擎技术主管并将需要改动的代码告知我们，以尽快的修复引擎中的严重错误。

需要明确的是，不论因为什么原因，您都可以更改自己所拥有的系统中的任何代码，而无需通知任何人你做了修改，但是您需要对修改的内容 注明修改原因 。但是在这种情况下，您需要对您所拥有的 代码安全及接口安全 负责，因为您是该系统代码的所有者。

2. 代码自文档化

EToD Engine 的主要工程目标之一是推广易于阅读、良好、干净、效率更高的代码。这是一个非常好的引擎开发方式，所以我们希望我们所编写的代码应该可读性很强，即使是很初级的引擎工程师也可以很快的上手引擎的开发。当然我们在某些系统开发上没有办法简化我们的代码，在这些系统之上做出简化很有可能会对引擎产生严重的错误。但是我们在整个引擎的开发之中，我们都应该遵守这种易读的开发方式，遵循这种结构清晰，简单以及代码文档化的开发方式。代码自文档化在代码部分中对代码逻辑进行了更全面的解释，并提供了描述性的命名符号等示例，包括对变量、函数等命名的示例与解释。我们更喜欢详细的描述性代码而不是自动生成的模板或函数式编程，这会产生更抽象的面向高级引擎工程师的代码，这些代码可能更难理解以及很难了解到我们所计算数据的用途。‎

理想情况下，您的代码应该能够尽可能地像一本小说一样易于阅读。如果您可以通过扩展变量名称 (尽可能的描述出变量的作用) 或添加额外的注释来使您的函数更容易理解 - 那请您坚持这样去做！‎

代码风格规范

到目前为止，EToD Engine 不需要一个详细的代码风格指南，因为我们认为我们的代码库中有足够的现有代码可以回答您可能遇到的每一个关于代码的风格问题。长话短说 - 如果您不知道用什么风格编写代码，请查阅我们代码库中的文件，多看看代码库中的代码风格，我们希望大家可以融入到我们现有的代码库中！因此我们简单的总结了一些代码编写的风格要点。

命名规范

Classes (类) ， functions (函数) ， member functions (成员函数) ， enums (枚举) ， namespaces (命名空间) ， source code file names (原代码文件名) ，和大多数其他 " titles " 始终使用 Pascal 命名规则 (例如 Win32 API 以及 Microsoft ' s C# 代码样式) 。

局部变量 (包括参数) 使用 Camel 命名规则。 私有成员变量 的前缀为 m_ 以及私有成员变量的首字母需要使用大写字母 (例如 m_VariableName ) 。 静态变量 (在编译单元 " 这里的编译单元是指 .cpp 文件 " 或类中) 的前缀为 s_ 静态变量的首字母同样需要使用大写 (例如 s_StaticVariable) 。

以下的示例演示了我们以上所总结的代码编写的相关风格要点：


namespace MyNamespace {

    static int s_StaticInt = 0;

    static void MyFunction();

    class ExampleClass
    {
    public:
        void ThisIsMyFunction(int inputVariable)
        {
            m_MemberVariable = inputVariable;

            std::string localVariable = std::to_string(inputVariable);
        }
    private:
        int m_MemberVariable = 0;
    };

}

未完待续 ...

开发者指南

开发守则

1. 代码所有制

2. 代码自文档化

代码风格规范

命名规范