docs(zh-CN): sync Chinese docs with latest upstream changes

This commit is contained in:
neo
2026-03-21 12:55:58 +08:00
parent 0af0fbf40b
commit e73c2ffa34
85 changed files with 11028 additions and 747 deletions

View File

@@ -0,0 +1,45 @@
---
paths:
- "**/*.cpp"
- "**/*.hpp"
- "**/*.cc"
- "**/*.hh"
- "**/*.cxx"
- "**/*.h"
- "**/CMakeLists.txt"
---
# C++ 编码风格
> 本文档基于 [common/coding-style.md](../common/coding-style.md) 扩展了 C++ 特定内容。
## 现代 C++ (C++17/20/23)
* 优先使用**现代 C++ 特性**而非 C 风格结构
* 当类型可从上下文推断时,使用 `auto`
* 使用 `constexpr` 定义编译时常量
* 使用结构化绑定:`auto [key, value] = map_entry;`
## 资源管理
* **处处使用 RAII** — 避免手动 `new`/`delete`
* 使用 `std::unique_ptr` 表示独占所有权
* 仅在确实需要共享所有权时使用 `std::shared_ptr`
* 使用 `std::make_unique` / `std::make_shared` 替代原始 `new`
## 命名约定
* 类型/类:`PascalCase`
* 函数/方法:`snake_case``camelCase`(遵循项目约定)
* 常量:`kPascalCase``UPPER_SNAKE_CASE`
* 命名空间:`lowercase`
* 成员变量:`snake_case_`(尾随下划线)或 `m_` 前缀
## 格式化
* 使用 **clang-format** — 避免风格争论
* 提交前运行 `clang-format -i <file>`
## 参考
有关全面的 C++ 编码标准和指南,请参阅技能:`cpp-coding-standards`

View File

@@ -0,0 +1,40 @@
---
paths:
- "**/*.cpp"
- "**/*.hpp"
- "**/*.cc"
- "**/*.hh"
- "**/*.cxx"
- "**/*.h"
- "**/CMakeLists.txt"
---
# C++ 钩子
> 本文档基于 [common/hooks.md](../common/hooks.md) 扩展了 C++ 相关内容。
## 构建钩子
在提交 C++ 更改前运行以下检查:
```bash
# Format check
clang-format --dry-run --Werror src/*.cpp src/*.hpp
# Static analysis
clang-tidy src/*.cpp -- -std=c++17
# Build
cmake --build build
# Tests
ctest --test-dir build --output-on-failure
```
## 推荐的 CI 流水线
1. **clang-format** — 代码格式化检查
2. **clang-tidy** — 静态分析
3. **cppcheck** — 补充分析
4. **cmake build** — 编译
5. **ctest** — 使用清理器执行测试

View File

@@ -0,0 +1,52 @@
---
paths:
- "**/*.cpp"
- "**/*.hpp"
- "**/*.cc"
- "**/*.hh"
- "**/*.cxx"
- "**/*.h"
- "**/CMakeLists.txt"
---
# C++ 模式
> 本文档基于 [common/patterns.md](../common/patterns.md) 扩展了 C++ 特定内容。
## RAII资源获取即初始化
将资源生命周期与对象生命周期绑定:
```cpp
class FileHandle {
public:
explicit FileHandle(const std::string& path) : file_(std::fopen(path.c_str(), "r")) {}
~FileHandle() { if (file_) std::fclose(file_); }
FileHandle(const FileHandle&) = delete;
FileHandle& operator=(const FileHandle&) = delete;
private:
std::FILE* file_;
};
```
## 三五法则/零法则
* **零法则**:优先使用不需要自定义析构函数、拷贝/移动构造函数或赋值运算符的类。
* **五法则**:如果你定义了析构函数、拷贝构造函数、拷贝赋值运算符、移动构造函数或移动赋值运算符中的任何一个,那么就需要定义全部五个。
## 值语义
* 按值传递小型/平凡类型。
*`const&` 传递大型类型。
* 按值返回(依赖 RVO/NRVO
* 对于接收后即被消耗的参数,使用移动语义。
## 错误处理
* 使用异常处理异常情况。
* 对于可能不存在的值,使用 `std::optional`
* 对于预期的失败,使用 `std::expected`C++23或结果类型。
## 参考
有关全面的 C++ 模式和反模式,请参阅技能:`cpp-coding-standards`

View File

@@ -0,0 +1,52 @@
---
paths:
- "**/*.cpp"
- "**/*.hpp"
- "**/*.cc"
- "**/*.hh"
- "**/*.cxx"
- "**/*.h"
- "**/CMakeLists.txt"
---
# C++ 安全
> 本文档扩展了 [common/security.md](../common/security.md),增加了 C++ 特有的内容。
## 内存安全
* 绝不使用原始的 `new`/`delete` — 使用智能指针
* 绝不使用 C 风格数组 — 使用 `std::array``std::vector`
* 绝不使用 `malloc`/`free` — 使用 C++ 分配方式
* 除非绝对必要,避免使用 `reinterpret_cast`
## 缓冲区溢出
* 使用 `std::string` 而非 `char*`
* 当安全性重要时,使用 `.at()` 进行边界检查访问
* 绝不使用 `strcpy``strcat``sprintf` — 使用 `std::string``fmt::format`
## 未定义行为
* 始终初始化变量
* 避免有符号整数溢出
* 绝不解引用空指针或悬垂指针
* 在 CI 中使用消毒剂:
```bash
cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
```
## 静态分析
* 使用 **clang-tidy** 进行自动化检查:
```bash
clang-tidy --checks='*' src/*.cpp
```
* 使用 **cppcheck** 进行额外分析:
```bash
cppcheck --enable=all src/
```
## 参考
查看技能:`cpp-coding-standards` 以获取详细的安全指南。

View File

@@ -0,0 +1,45 @@
---
paths:
- "**/*.cpp"
- "**/*.hpp"
- "**/*.cc"
- "**/*.hh"
- "**/*.cxx"
- "**/*.h"
- "**/CMakeLists.txt"
---
# C++ 测试
> 本文档扩展了 [common/testing.md](../common/testing.md) 中关于 C++ 的特定内容。
## 框架
使用 **GoogleTest** (gtest/gmock) 配合 **CMake/CTest**
## 运行测试
```bash
cmake --build build && ctest --test-dir build --output-on-failure
```
## 覆盖率
```bash
cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" ..
cmake --build .
ctest --output-on-failure
lcov --capture --directory . --output-file coverage.info
```
## 内存消毒工具
在 CI 中应始终使用内存消毒工具运行测试:
```bash
cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
```
## 参考
查看技能:`cpp-testing` 以获取详细的 C++ 测试模式、TDD 工作流以及 GoogleTest/GMock 使用指南。