ViewDesignEngine/docs/04-编码实现/01-编码规范.md

编码规范

目录

1. C++ 标准
2. 命名规范
3. 头文件规范
4. 代码风格
5. 注释规范
6. 内存管理
7. 错误处理
8. 性能规范

---

1. C++ 标准

• 目标标准：C++17
• 编译器：GCC 9+, Clang 12+, MSVC 2019+
• 允许的 C++17 特性：
  • structured bindings、if constexpr、fold expressions
  • std::string_view、std::optional
  • [[nodiscard]]、[[maybe_unused]]
  • CTAD（类模板参数推导）

---

2. 命名规范

元素	风格	示例
命名空间	snake_case	vde::core
类/结构体	PascalCase	HalfedgeMesh
函数/方法	snake_case	compute_convex_hull()
成员变量	snake_case_	vertices_
常量	UPPER_SNAKE_CASE	MAX_ITERATIONS
枚举值	kPascalCase	kSuccess
宏	VDE_UPPER_SNAKE	VDE_VERSION_MAJOR

---

3. 头文件规范

#pragma once  // 优先使用

// 包含顺序（每组间空行分隔）：
// 1. 对应的 .h 文件（.cpp 中）
// 2. C++ 标准库
// 3. 第三方库（Eigen）
// 4. 本项目头文件

#include "vde/core/point.h"

#include <cmath>
#include <vector>

#include <Eigen/Core>

#include "vde/core/aabb.h"

---

4. 代码风格

• 缩进：4 空格，不使用 Tab
• 行宽：上限 100 字符
• 格式化：统一使用 .clang-format（Google 风格变体）
• 短函数：单行内联
• 大括号：函数/类/结构体后换行，控制流不换行

---

5. 注释规范

• 公开 API：使用 Doxygen 风格（///）
• 内部实现：使用 // 行注释
• 复杂算法：必须注释算法来源（论文引用或公式）
• 禁止：注释掉的代码（使用版本控制回溯）

---

6. 内存管理

• 禁止裸 new/delete
• 使用 std::make_unique / std::make_shared
• 大块连续内存使用 std::vector
• 小型对象优先栈分配
• 性能关键路径使用自定义 MemoryPool

---

7. 错误处理

// 公开 API 返回值类型
template <typename T>
using Result = tl::expected<T, ErrorCode>;

// 内部断言
assert(condition && "message");

• 公开 API 不抛异常
• 内部可抛异常，但必须提供异常安全保证

---

8. 性能规范

• 函数参数：基本类型传值，大对象传 const&，sink 参数传 &&
• 循环中避免重复计算：hoist 不变量
• 容器预分配：reserve() 已知大小
• 避免隐藏的临时对象拷贝