kiz modern C++ 库编码规范

1. 头文件

• 使用 #pragma once 作为头文件保护，不使用 #ifndef 宏保护。
• 头文件的包含顺序按先放本模块，再放第三方

2. 缩进与格式

• 命名空间 ks 内部不缩进。
• 左大括号不换行。
• 条件、循环、关键字与括号之间留空格。
• 函数与函数之间空一行。

3. 命名空间与模块

• 不允许使用 inline namespace，会降低代码可读性与结构清晰度。
• **不允许在头文件使用using namespace**会降低代码可读性与结构清晰度。
• 建议一个文件一个类，类名和文件名相同
• 文件/文件夹名使用小写下划线命名法。
• 建议将实现细节放入内部命名空间（如detail）。

4. 函数写法

• 建议统一使用后置返回类型：

auto func() -> int;

• void 函数可以保持传统写法：

void func();

• • 鼓励对短小函数使用inline，移动构造/赋值应标记noexcept以提高性能。

5. 命名规则

• 变量、函数：小写 + 下划线 snake_case
• 类型、类、结构体：大驼峰 PascalCase
• 私有成员变量：末尾加下划线 data_

6. 变量与类型

• 优先使用 auto 推导变量类型，不使用冗余的 auto*。
• 使用int* name int& name而不是int *name int &name
• 固定大小数组优先使用 C 风格数组，不建议使用 std::array。
• 尽量不使用全局变量。
• 优先使用定长/明确大小类型： uint8_t、int32_t、size_t、uintptr_t 等， 不建议使用模糊长度的原始类型：int、long、long long 等。

7. 类与成员布局

• 类内部按逻辑顺序排列，不按 public/private/protected 分段：
  1. 私有字段
  2. 公开字段和常量
  3. 构造函数 / 析构函数
  4. 公开接口
  5. 私有方法
• 强制要求初始化列表按声明顺序，建议对单参数构造函数使用explicit。
• 不推荐使用虚函数，优先使用静态派发。

8. 内存与所有权

• 使用智能指针/所有权指针管理动态内存。
• 尽量减少裸指针；如必须使用，明确是观察而非持有。

9. 类型转换（重要）

• 禁止使用 C 风格强制转换 (Type)expr。
• 统一使用 C++ 显式转换：
  • static_cast：安全、普通类型转换
  • reinterpret_cast：底层指针/内存重解释（高危，需注释）
  • const_cast：仅用于兼容 C 接口等极端场景

10. 错误与安全

• 不推荐使用 C++ 异常与 try-catch。
• 所有可失败操作统一返回 ks::Result。
• 不推荐使用 RTTI：不推荐使用 dynamic_cast、typeid。
• 优先使用断言保证前提，而不是运行时检查。
• 数组访问优先 a[0]，不使用 a.at(0)（效率低）。

11. 常量与枚举

• 多使用 enum class / constexpr， 禁止魔法数字、禁止滥用宏定义常量/函数。

12. 注释与文档

• 文档统一使用 /// 精简注释， 只写作用 + 副作用 + 关键前提，不写冗余长文本。
• 不使用冗长 /**/ 块注释。

13. 平台与编译器差异

• 尽量不使用编译器提供的扩展语法，以适配不同编译器。
• 使用明确的宏命名风格（如OS_WIN），建议将平台差异封装在独立文件中。