43 lines
3.9 KiB
Markdown
43 lines
3.9 KiB
Markdown
# NanoEra 项目设计编码规范 (NanoEra Project Design and Coding Standards) V1.0
|
||
## 一、模块
|
||
1. 模块是项目的基本组成单元，每个模块应有且仅有明确的功能。
|
||
2. 对于单个模块，其应该由以下两个部分组成：
|
||
* 模块内容声明部分：包含模块的头文件(`.h`或`.hpp`文件)，用于声明模块的接口和数据结构等。
|
||
* 模块实现部分：包含模块的源代码文件(`.cpp`或`.c`文件)，用于实现模块的功能逻辑。
|
||
* 注：对于较为复杂的单个模块，可以使用多个头文件与源代码文件，但是必须全部组织于名为模块名称的文件夹内。
|
||
3. 模块之间允许存在依赖关系，但应杜绝模块内容声明部分的循环依赖，以确保模块的独立性和可维护性。*特殊地，模块的实现之间允许循环依赖，如对于模块A和模块B，`B.cpp`导入了'A.h'且'A.cpp'导入了'B.h'是可以出现的，但是`A.h`与`B.h`间不允许出现任何引用关系。*
|
||
4. **2.4节**中`extended_folders.list`里的保留文件夹名不应该作为模块名使用。
|
||
|
||
## 二、文件目录组织规范
|
||
1. 项目根目录下应至少包含如下文件夹：
|
||
* `include/`：存放头文件。
|
||
* `src/`：存放源代码文件。
|
||
* `lib/`：存放第三方库文件。
|
||
* `build/`：存放编译生成的文件***(该文件夹应该由编译程序在构建项目时自动创建，并在清理构建时自动删除，而不是手动创建)***
|
||
* `res/`：存放资源文件，如项目图标等内容。
|
||
* `docs/`：存放项目文档。
|
||
* `tests/`：存放测试代码。
|
||
* `scripts/`：存放构建和部署脚本。
|
||
* `experiments/`：用于项目测试记录留证和临时实验代码和数据归档。
|
||
* 除此之外，项目根目录下还可以创建其他文件夹，但是必须在`git push`推送代码时注明文件夹用途。
|
||
2. 对于头文件文件夹(`include/`文件夹)的特殊要求：
|
||
* 原则上，项目的`include/`文件夹内不依赖任何非编译器内置库的模块和外部模块应该分别存储于`basic/`和`external/`两个子文件夹中。
|
||
* 额外地，可以创建一些文件夹用于进行模块分类，但由于部分模块存储于文件夹中而不是单一文件中，故可在`include/`文件夹中创建`extended_folders.list`声明用于模块分类的文件夹，每行一个文件夹名称(格式如本文)。相应地，这部分保留文件夹名不应该作为模块名。
|
||
3. 对于源代码文件夹(`src/`文件夹)的特殊要求：
|
||
* 源代码文件应与其对应的头文件文件夹结构保持一致。
|
||
4. `scripts/`文件夹内可以存储如下脚本文件：
|
||
* `export_modules_requirements.sh`：基于`include/`和`src/`中的源码和`include/extended_folders.list`导出项目模块依赖关系。
|
||
* `check_code.sh`：用于检查代码规范。
|
||
5. 所有文件应统一采用UTF-8编码。如需多编码形式，可以在`scripts/`文件夹内创建相应的转换脚本。
|
||
|
||
## 三、编码规范
|
||
1. 命名规范：
|
||
* 文件夹、文件夹名应使用小写单词+下划线形式命名。
|
||
* 函数名、变量名应使用小写单词+下划线形式命名。
|
||
* 类、结构体等数据结构名应使用大驼峰命名法，数据结构成员变量及函数应后缀下划线进行标记。
|
||
* 全局常量、宏定义、宏函数等应使用大写单词+下划线形式。
|
||
* 全局变量应前缀`g_`并使用小写单词+下划线形式命名。
|
||
1. 对于编码时头文件引用的要求：
|
||
* 对于`include/`文件夹中的头文件，其应保证只引用模块接口和数据结构声明所必须的头，其余如实现时才需要的头文件应该在实现文件中引用。
|
||
* 对于`src/`文件夹中的实现文件，其同样应保证只引用该文件所必须的头文件，同时不能引用模块头文件中已经引用过的头文件(因为模块实现文件中一定会包含模块声明的头文件，故应避免冲突include)。
|