Aethera/Project_naming_conventions.md

项目命名规范

• 类型、结构体、枚举、Concept、类型别名：Upper_Snake_Case

Scene_Base
Frame_Request_Result
Renderable_Id

• 函数、参数、局部变量、常量：lower_snake_case

render_frame()
frame_count
default_capacity

• 成员变量：lower_snake_case

scene
pending_exception

• 枚举值：lower_snake_case

enum class Frame_Request_Result {
    none,
    cancelled,
    renderer_unavailable
};

• 模板类型参数：Upper_Snake_Case

template <class Data_Type, class Observer_Type>

• 命名空间：lower_snake_case

namespace renderive::render_3d

• 文件名与主要类型一致：Upper_Snake_Case

Scene_Base.hpp
Gpu_Completion_Service.cpp
Low_Latency_Strategy.inl

• 内部实现统一使用 detail 命名空间。

普通字段注释

• 普通数据字段必须在声明同行使用 /* ... */ 注释；不要为每个普通字段单独占用前一行。
• 同一个结构体、类或连续字段分组内，行尾注释的起始列必须对齐。以该分组中最长的声明为基准，并至少保留一个空格。
• 注释应说明字段的业务含义；存在单位、有效条件、触发时机、零值语义、所有权或生命周期约束时，必须一并写明。
• 禁止只把字段名或类型换成中文重复一遍，也不要把与字段无关的实现流程写进字段注释。
• 复杂不变量可在字段分组前增加块注释，但字段本身仍应保留简短、对齐的行尾摘要，避免为了塞入全部说明制造超长单行。
• 函数、类型别名、嵌套类型和 CRTP 定制点不属于普通字段，应使用声明前注释说明契约。

bool rebuilt{};                         /* 本次提交是否重新构建任务图。 */
std::uint64_t execution_time_ns{};      /* 本次执行耗时，单位为纳秒；未执行时为 0。 */

Private 实现放置

• 对外 .hpp 中只前置声明嵌套的 struct Private;，不得展开其字段、内部派发表、线程状态、缓冲角色或实现函数。
• Owner::Private 的完整声明放在对应 .ipp 中；模板实现继续放在 .ipp，非模板实现可放在 .cpp。
• 派生方可覆盖的 CRTP 函数和能力契约，必须在 .ipp 的 Private 完整声明处逐项注释；派生 Private 必须继承 Prev_Private。
• 禁止在 .hpp 与 .ipp 各保留一份 Private 定义，也禁止为旧布局保留兼容转发层。

更完整的代码组织和设计约束见 项目细节规范。

总规则：类型使用大写下划线；值、函数和成员变量使用小写下划线；普通字段使用对齐的同行注释；Private 的完整实现声明放在对应 .ipp。