# 代码速览指南（第四版）

### 第四版前言

进一步优化了表达方式，将源码目录功能和阅读顺序统一为一个表格。

——2025年10月5日


### 第三版前言

使用了表格等更清晰的表述方式。

——2025年8月19日

### 第二版前言

去除了一些情绪化的描述，使该文档更加术语化。

——2025年7月29日

### 第一版前言

本指南将于其发布时起指导作用，直到下一版发布时将会过时。
本指南旨在让开发者在5分钟内快速了解项目架构以及阅读顺序。

——2024年10月15日

### 一些误区

* 文件后缀

本项目中，移植接口的源码后缀统一为``.h``或``.hpp``格式；主体实现部分中，每一个源码子目录由一个``.hpp``文件来统领其他的``.cpp``文件（要求开发者只需包含此``.hpp``文件即可调用该子目录下的所有代码）。

``.hpp``和``.cpp``都可以用于代码的定义和实现，两个后缀名在本项目当中仅用来区分哪个文件统领了源码目录。

以上仅适用一般情况，并非强制要求。

* include的使用

由于本项目并未采用“定义与实现分离开来，后期统一链接”的形式。

我们不建议开发者将此项目中的``#include``看作C/C++中的包含，而是看作import（类似java，python的设计）。

因为本项目的编译指令只有一条，不存在链接，因此我们不建议两个文件之间相互包含（请尽量编写不循环引用的代码）。

### 项目架构及源码阅读顺序

我们来介绍与源码有关的目录：
我们将用一个表格来解释每个目录的用途。目录从顶至底，也是推荐的源码目录阅读顺序。

|目录名|用途|
|:-|:-|
|``include``|该目录用于存放移植接口的定义和不同方法的实现，此目录又有多个子目录。其中``interface``子目录用于存放移植接口的定义，其余子目录是移植接口的不同方法实现。移植接口的更多介绍位于``移植接口开发指导.md``|
|``src/ast``|该目录存储抽象语法树（AST）的数据结构，主要用于语法分析。|
|``src/config``|该目录存储程序运行的默认配置参数。|
|``src/exception``|该目录存储报错信息的生成函数。|
|``src/compiler``|该目录存储编译器的实现。|
|``src/data_type``|该目录存储stamon数据类型的数据结构。|
|``src/vm``|该目录存储虚拟机的实现。|
|``src/sfn``|该目录存储Stamon调用虚拟机外部库的实现。|
|``src/ir``|该目录存储Stamon的中间代码数据结构，中间代码生成器以及解析器。|
|``src/action``|该目录用于存储分步行动机制的实现代码（包括一些文件的编解码实现）。|
|``src``|该目录存储主体实现部分的代码，与移植接口实现分割开来，以此实现更强的可移植性。该目录下存放有若干子目录和项目主要文件（例如程序的入口源码）。|
|``src/bin-include``|该目录存储Stamon的标准库源码。|