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

### 第一版前言

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

——2024年10月15日

### 一些误区

* 文件后缀

很多人反映源码的后缀名很奇怪。

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

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

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

* include的使用

由于本项目并未采用“定义与实现分离开来，后期统一链接”的形式，因此源码包含的结构有点奇怪。

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

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

**我们承认我们并没有在编写“纯正的现代C++代码”。**

* 代码风格

尽管这个项目是用C++编写的，但是其掺杂了很多java的元素。

例如把所有的成员都写在类里、一个大类编写在一个文件里、代码格式化风格以及上述所说的代码引用方法。请阅读源码时不要见怪。

### 项目架构

我们来介绍与源码有关的目录：

* ``include``

该目录用于存放依赖库文件，此目录又有多个子目录。其中``template``子目录用于存放依赖库模板，其余子目录是依赖库的不同平台实现。

* ``src``

该目录存储主体实现部分的代码，与依赖库实现分割开来，以此实现更强的可移植性。该目录下存放有若干子目录和项目主要文件（例如程序的入口源码）。

* ``src/ast``

该目录存储抽象语法树（AST）的数据结构，主要用于语法分析。

* ``src/data_type``

该目录存储stamon数据类型的数据结构。

* ``src/bin-include``

该目录存储Stamon的标准库源码。

* ``src/error``

该目录存储报错信息的生成函数。

* ``src/config``

该目录存储程序运行的默认配置参数。

* ``src/compiler``

该目录存储编译器的实现。

* ``src/ir``

该目录存储Stamon的中间代码数据结构，中间代码生成器以及解析器。

* ``src/sfn``

该目录存储Stamon调用虚拟机外部库的实现。

* ``src/vm``

该目录存储虚拟机的实现。

* ``src/action``

该目录用于存储分步行动机制的实现代码（包括一些文件的编解码实现）。

### 源码阅读顺序

我们建议开发者先从基础出发，一步步看到主函数的实现。

因此一个合理的源码阅读流程是（以目录为单位）：

* ``include``
* ``src/ast``
* ``src/config``
* ``src/error``
* ``src/compiler``
* ``src/vm``
* ``src/sfn``
* ``src/action``
* ``src/ir``
* ``src``
* ``src/bin-include``

