# 编码规范

## 目录

1. [C++ 标准](#1-c-标准)
2. [命名规范](#2-命名规范)
3. [头文件规范](#3-头文件规范)
4. [代码风格](#4-代码风格)
5. [注释规范](#5-注释规范)
6. [内存管理](#6-内存管理)
7. [错误处理](#7-错误处理)
8. [性能规范](#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. 头文件规范

```cpp
#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. 错误处理

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

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

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

---

## 8. 性能规范

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