# 学习笔记 → 示例代码 转化流程

将 `raw/` 中的 Markdown 学习笔记转化为可编译、通过 linter 检查的示例代码。

## 核心原则

**有机整合，不要割裂。** 一个文档的多个知识点应该融入同一段代码，而非每个知识点单独写一个示例。

反例（割裂）：

```cpp
// 知识点1：封装
class A { public: int x; };

// 知识点2：继承
class B : public A {};

// 知识点3：多态
// ...又一个独立的类
```

正例（整合）：

```cpp
// 一个 Vehicle 继承体系，同时覆盖封装、构造析构、深拷贝、继承、多态
class Vehicle { ... };
class Car : public Vehicle { ... };
class Truck final : public Vehicle { ... };
```

## 流程

### 1. 读取原始笔记

读取目标 `.md` 文件，通读全部知识点。

### 2. 提取核心知识点

从笔记中提炼出所有需要演示的知识点，按主题分组。

### 3. 设计代码结构

根据语言特性和知识点类型选择组织方式：

**OOP 语言（C++、Java、C# 等）**：用 2~3 个有继承关系的类，让父类承载大部分知识点，子类演示扩展和多态。

**过程式语言（C 等无类语言）**：按功能模块组织，一个 `.c` 文件覆盖多个知识点，用函数分组，用注释标注知识点编号。

**算法示例**：一个完整的算法实现（如排序、查找、链表操作），在实现过程中自然覆盖该文档的所有知识点。

设计目标：

- 知识点之间有逻辑关联，不是孤立的
- 代码能体现知识点之间的协作关系
- 结构紧凑，没有为了凑知识点而加的冗余代码

### 4. 编写代码

- 简洁为上，不引入不必要的复杂度
- 关键字和概念处加注释，说明"这是什么"和"为什么这样写"
- 不使用语言级别的 namespace/import 全局导入，标准库类型显式限定
- 魔法数字用命名常量替代
- 变量名语义清晰，长度符合 linter 要求
- 不写冗余代码：能一行的不写三行，能省略的模板代码不重复

### 5. 按编号标注知识点

注释中用 `1.` `2.` `3.` 等简单编号标注每个知识点对应的代码位置，便于查阅。

### 6. 运行 linter / 静态分析

使用项目根目录下的 linter 配置文件：

```bash
# C++
clang-tidy "文件路径" -p "项目根目录" -- -std=c++17

# C
clang-tidy "文件路径" -p "项目根目录" -- -std=c11

# Python
ruff check "文件路径"

# JavaScript / TypeScript
eslint "文件路径"

# Go
golangci-lint run
```

### 7. 重新检查直到用户代码 0 警告

重复步骤 4-6，直到 linter 只报告外部依赖的警告，用户代码无警告。

### 8. 验证逻辑正确性

手动确认：

- 静态成员计数正确（构造时 `++`、析构时 `--`）
- 深拷贝真正分配了新资源
- 虚析构/析构函数存在（父类指针释放子类不泄漏）

## 语言适配

| 语言       | 组织方式                    | 注意事项                                     |
| ---------- | --------------------------- | -------------------------------------------- |
| C++        | 类继承体系                  | 虚析构、Rule of Five、const 成员函数         |
| C          | 按功能模块分函数组          | 结构体 + 函数指针模拟多态，static 文件作用域 |
| Java       | 接口 + 抽象类 + 实现类      | 强制 Rule of Five，接口隔离                  |
| Python     | 基类 + 子类，或函数式       | `@property`、`__init__`、`abc.ABC`     |
| Go         | 结构体 + 方法，接口隐式实现 | 无继承，用组合替代                           |
| JavaScript | 原型链或 class 语法         | `class`、`extends`、`static`           |
| 算法       | 单文件完整实现              | 主函数演示 + 核心算法函数，注释标注复杂度    |

## 注意事项

- 注释精简，只在关键知识点处标注，不写大段重复解释
- 语言特有属性（如 C++ 的 `[[nodiscard]]`）按项目 linter 配置要求添加
- `friend` 等破坏封装的用法，注释中说明"谨慎使用"
- 不要为了覆盖知识点而写无意义的代码，每个知识点都应有实际用途