83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 项目命名规范
|
|
|
|
* 类型、结构体、枚举、Concept、类型别名：`Upper_Snake_Case`
|
|
|
|
```cpp
|
|
Scene_Base
|
|
Frame_Request_Result
|
|
Renderable_Id
|
|
```
|
|
|
|
* 函数、参数、局部变量、常量：`lower_snake_case`
|
|
|
|
```cpp
|
|
render_frame()
|
|
frame_count
|
|
default_capacity
|
|
```
|
|
|
|
* 成员变量：`lower_snake_case`
|
|
|
|
```cpp
|
|
scene
|
|
pending_exception
|
|
```
|
|
|
|
* 枚举值：`lower_snake_case`
|
|
|
|
```cpp
|
|
enum class Frame_Request_Result {
|
|
none,
|
|
cancelled,
|
|
renderer_unavailable
|
|
};
|
|
```
|
|
|
|
* 模板类型参数：`Upper_Snake_Case`
|
|
|
|
```cpp
|
|
template <class Data_Type, class Observer_Type>
|
|
```
|
|
|
|
* 命名空间：`lower_snake_case`
|
|
|
|
```cpp
|
|
namespace renderive::render_3d
|
|
```
|
|
|
|
* 文件名与主要类型一致：`Upper_Snake_Case`
|
|
|
|
```text
|
|
Scene_Base.hpp
|
|
Gpu_Completion_Service.cpp
|
|
Low_Latency_Strategy.inl
|
|
```
|
|
|
|
* 内部实现统一使用 `detail` 命名空间。
|
|
|
|
## 普通字段注释
|
|
|
|
* 普通数据字段必须在声明同行使用 `/* ... */` 注释；不要为每个普通字段单独占用前一行。
|
|
* 同一个结构体、类或连续字段分组内，行尾注释的起始列必须对齐。以该分组中最长的声明为基准，并至少保留一个空格。
|
|
* 注释应说明字段的业务含义；存在单位、有效条件、触发时机、零值语义、所有权或生命周期约束时，必须一并写明。
|
|
* 禁止只把字段名或类型换成中文重复一遍，也不要把与字段无关的实现流程写进字段注释。
|
|
* 复杂不变量可在字段分组前增加块注释，但字段本身仍应保留简短、对齐的行尾摘要，避免为了塞入全部说明制造超长单行。
|
|
* 函数、类型别名、嵌套类型和 CRTP 定制点不属于普通字段，应使用声明前注释说明契约。
|
|
|
|
```cpp
|
|
bool rebuilt{}; /* 本次提交是否重新构建任务图。 */
|
|
std::uint64_t execution_time_ns{}; /* 本次执行耗时，单位为纳秒；未执行时为 0。 */
|
|
```
|
|
|
|
## Private 实现放置
|
|
|
|
* `.hpp` 中所有函数只能声明，禁止编写函数体；该限制同样适用于构造函数、薄壳函数和模板函数。模板定义放对应 `.ipp`，非模板定义放 `.cpp` 或仅供头文件实例化的 `.ipp`。
|
|
* 对外 `.hpp` 中只前置声明嵌套的 `struct Private;`，不得展开其字段、内部派发表、线程状态、缓冲角色或实现函数。
|
|
* `Owner::Private` 的完整声明放在对应 `.ipp` 中；模板实现继续放在 `.ipp`，非模板实现可放在 `.cpp`。
|
|
* 派生方可覆盖的 CRTP 函数和能力契约，必须在 `.ipp` 的 `Private` 完整声明处逐项注释；派生 `Private` 必须继承 `Prev_Private`。
|
|
* 禁止在 `.hpp` 与 `.ipp` 各保留一份 `Private` 定义，也禁止为旧布局保留兼容转发层。
|
|
|
|
更完整的代码组织和设计约束见 [项目细节规范](./Project_detail_specification.md)。
|
|
|
|
**总规则：类型使用大写下划线；值、函数和成员变量使用小写下划线；普通字段使用对齐的同行注释；Private 的完整实现声明放在对应 `.ipp`。**
|