v0.1.0: 初始工程骨架 — 7模块 40头文件 32源文件 17文档 Apache-2.0

2026-07-23 05:27:51 +00:00
commit 02d0520aa5
133 changed files with 5350 additions and 0 deletions
@@ -0,0 +1,115 @@
+# 编码规范
+
+## 目录
+
+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()` 已知大小
+- 避免隐藏的临时对象拷贝