# 项目命名规范

* 类型、结构体、枚举、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`。**