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

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

核心原则

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

反例（割裂）：

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

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

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

正例（整合）：

// 一个 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 配置文件：

# 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 等破坏封装的用法，注释中说明"谨慎使用"
不要为了覆盖知识点而写无意义的代码，每个知识点都应有实际用途

markdown-to-code-workflow.md 4.1 KB História Raw

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