Squashed 'docs/standards/playbook/' content from commit e504a68
git-subtree-dir: docs/standards/playbook git-subtree-split: e504a689dcf2e2fdeeb64097930347d504e68f5f
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# TSL 代码风格（Code Style）
|
||||
|
||||
本章节规定 TSL 代码的结构与格式约定。
|
||||
|
||||
## 1. 文件与组织
|
||||
|
||||
- 一个文件只做一件事；职责明确。
|
||||
- 文件名使用 `PascalCase`，并与文件内唯一的顶层声明同名（语法要求）。扩展名按类型使用 `.tsl`/`.tsf`（两者都属于 TSL 源文件，风格规则一致）。
|
||||
- 避免循环依赖；公共能力下沉到可复用模块。
|
||||
- 同类代码按“对外 API → 核心实现 → 辅助工具 → 测试/示例”的顺序组织。
|
||||
|
||||
## 2. 格式（Formatting）
|
||||
|
||||
### 2.1 缩进与空白
|
||||
|
||||
- 使用**空格缩进**，禁止 Tab。
|
||||
- 默认缩进 **4 个空格**；继续缩进保持与上层语义一致。
|
||||
- 行尾不留空格；文件以换行符结尾。
|
||||
- 逻辑块之间用空行分隔，不要用空行堆砌。
|
||||
|
||||
### 2.2 行宽与换行
|
||||
|
||||
- 单行建议不超过 **100 字符**；超过时应换行以保持可读性。
|
||||
- 换行遵循“**断在运算符后**、对齐到语义层级”的原则。
|
||||
- 长字符串/URL 可适当超出，但避免影响阅读。
|
||||
|
||||
### 2.3 begin/end 与代码块
|
||||
|
||||
- 代码块使用统一的块结构（示例为伪代码，按 TSL 语法调整）：
|
||||
|
||||
```tsl
|
||||
if cond then
|
||||
begin
|
||||
DoSomething()
|
||||
end
|
||||
else
|
||||
begin
|
||||
DoOther()
|
||||
end
|
||||
```
|
||||
|
||||
- 多语句分支使用 `begin/end` 包裹：在 `then/else` 后换行写 `begin`，`end` 单独成行。
|
||||
- `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
|
||||
|
||||
### 2.4 运算符与分隔符
|
||||
|
||||
- 二元运算符两侧加空格：`a + b`、`x == y`。
|
||||
- 一元运算符不加空格：`!flag`、`-value`。
|
||||
- 逗号后加空格：`f(a, b, c)`。
|
||||
- 不要为了对齐而插入多余空格；让格式由缩进表达结构。
|
||||
|
||||
### 2.5 控制流
|
||||
|
||||
- 多语句分支必须使用 `begin/end`；单语句分支可省略 `begin/end`，写成单行（如 `if cond then stmt`）。
|
||||
- 复杂条件拆分为具名布尔变量或小函数。
|
||||
- 早返回优于深层嵌套：
|
||||
|
||||
```tsl
|
||||
if !ok then return err
|
||||
// main path
|
||||
```
|
||||
|
||||
## 3. 注释（Comments）
|
||||
|
||||
注释用于解释**为什么**以及必要的背景，而不是重复代码。
|
||||
|
||||
### 3.1 文件级注释
|
||||
|
||||
- 文件开头说明用途、主要职责、关键依赖/约束。
|
||||
- 若文件实现某个对外 API，写明入口与预期行为。
|
||||
|
||||
### 3.2 函数/接口注释
|
||||
|
||||
- 对外可见的函数必须写注释，包含：
|
||||
- 做什么（行为）
|
||||
- 入参/返回值含义（必要时含单位、范围）
|
||||
- 关键副作用与异常情况
|
||||
- 注释使用完整句子，末尾带标点。
|
||||
|
||||
### 3.3 行内注释
|
||||
|
||||
- 用于解释复杂逻辑、非直观边界条件、性能/安全考量。
|
||||
- 避免“显而易见注释”：
|
||||
|
||||
```tsl
|
||||
count = count + 1 // bad: obvious
|
||||
```
|
||||
|
||||
### 3.4 TODO/FIXME
|
||||
|
||||
- 统一格式：`TODO(name): ...` / `FIXME(name): ...`
|
||||
- 写清原因和期望修复方向，而非“留个坑”。
|
||||
|
||||
## 4. 代码实践（Best Practices）
|
||||
|
||||
### 4.1 变量与常量
|
||||
|
||||
- 默认使用不可变/只读（如语法支持 `const` 或等价机制）。
|
||||
- 变量声明与第一次使用尽量靠近。
|
||||
- 避免隐藏式类型转换与隐式全局。
|
||||
|
||||
### 4.2 函数设计
|
||||
|
||||
- 函数参数建议显式写类型注解，提升可读性与工具检查能力。
|
||||
- 无返回值函数显式标注返回类型为 `void`。
|
||||
|
||||
```tsl
|
||||
function Func(a: string; b: ClassName): void;
|
||||
```
|
||||
|
||||
- 单一职责；函数过长说明拆分点已出现（建议 ≤ 40–60 行）。
|
||||
- 参数顺序：输入参数在前，输出/回调在后。
|
||||
- 尽量避免超过 5 个参数；必要时封装为对象（class/unit）。
|
||||
|
||||
### 4.3 错误处理
|
||||
|
||||
- 错误必须显式处理：返回错误、抛出异常或记录并降级（按项目约定）。
|
||||
- 不要吞掉异常/错误；必须加注释说明原因。
|
||||
|
||||
### 4.4 性能与可测试性
|
||||
|
||||
- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。
|
||||
- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。
|
||||
@@ -0,0 +1,151 @@
|
||||
# TSL 命名规范（Naming）
|
||||
|
||||
本仓库命名规则与 Google C++ Style Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。
|
||||
|
||||
## 1. 选名原则
|
||||
|
||||
- **可读一致**：名字清晰可读，并随可见范围调整具体程度。
|
||||
- **少用生僻缩写**：能写全称就写全称。
|
||||
- **驼峰/帕斯卡中的缩写规则**：缩写（首字母缩写/词组缩写）在 `PascalCase`/`camelCase` 中**按一个单词处理**，写成“首字母大写其余小写”，不要写一串全大写。
|
||||
- 示例：`UserId`（不是 `UserID`）、`UrlTable`（不是 `URLTable`）、
|
||||
`StartRpcServer`（不是 `StartRPCServer`）、`HttpClient`（不是 `HTTPClient`）。
|
||||
- **避免无意义词**：如 `data`、`info`、`tmp`、`handle` 等。
|
||||
|
||||
## 2. 命名风格总览
|
||||
|
||||
对于以下规则，“单词”指英文中不带空格的词。
|
||||
|
||||
- `snake_case`：全小写，下划线分隔单词，用于普通变量/参数等；私有类成员变量在此基础上末尾加下划线。
|
||||
- `PascalCase`（`UpperCamelCase`）：每个单词首字母大写，无下划线，用于类型、顶层函数/方法、property，以及（少量）公有成员字段。
|
||||
|
||||
**大小写与关键字约定**
|
||||
|
||||
- TSL 语言大小写无关，但本指南仍要求按约定使用大小写以提升可读性；不要用仅大小写不同的名字区分不同实体。
|
||||
- 所有语法关键字统一使用全小写书写，例如 `if`、`for`、`class`、`function`、`unit`、`return` 等。
|
||||
- 调用内置/标准库方法时，推荐保持官方大小写形式（`aaBBCC`/lowerCamelCase），例如 `getSysParams("xxx")`。
|
||||
|
||||
## 3. 类型命名（Type Names）
|
||||
|
||||
TSL 的顶层声明只有三种：`class`、`unit`、`function`。
|
||||
|
||||
- **类（class）与单元（unit）**使用 `PascalCase`，不带下划线。
|
||||
- **顶层函数（function）**使用 `PascalCase`，详见函数命名章节。
|
||||
- 示例：`UserAccount`、`OrderUnit`、`LoadMarketData()`。
|
||||
|
||||
## 4. 文件命名与顶层声明（File Names）
|
||||
|
||||
TSL 的语法要求：每个文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。
|
||||
|
||||
- 顶层声明可能是 `class`、`unit` 或 `function`（见类型命名）。
|
||||
- `.tsl` 脚本文件：顶层声明只能是 `function`，因此文件基名 = 顶层函数名。
|
||||
- `.tsf` 代码文件：顶层声明可为 `class`/`unit`/`function`，文件基名需与之同名。
|
||||
- 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。
|
||||
|
||||
命名建议：
|
||||
|
||||
- 基名统一使用 `PascalCase`，与顶层声明的推荐写法一致。
|
||||
- 示例：
|
||||
- `LoadMarketData.tsl` 中定义 `function LoadMarketData(...)`.
|
||||
- `UserAccount.tsf` 中定义 `type UserAccount = class ... end;`.
|
||||
- `DocxEnumerations.tsf` 中定义 `unit DocxEnumerations; ... end.`
|
||||
|
||||
注：TSL 大小写无关，实际编译时按大小写比较不会出错，但仍应保持文件名与声明名的推荐写法一致以便检索与协作。
|
||||
|
||||
## 5. 变量命名（Variable Names）
|
||||
|
||||
### 5.1 普通变量与参数
|
||||
|
||||
- **局部变量、函数参数、非成员变量**使用 `snake_case`。
|
||||
- 若参数名与 TSL 关键字冲突导致编译失败，使用前导下划线的 `snake_case` 作为例外，例如 `_type`、`_unit`。
|
||||
- 前导下划线 `_` **仅用于上述关键字冲突的参数场景**，不要用于其他局部变量、成员变量、函数/类型/单元名称或全局变量。
|
||||
- 示例：`table_name`、`max_retry_count`、`user_id`。
|
||||
|
||||
### 5.2 类成员（Class Data Members）
|
||||
|
||||
- **私有成员变量**使用 `snake_case_`（尾随下划线）。
|
||||
- 尾随下划线 `_` **仅用于私有成员变量**，不要用于局部变量、参数、公有成员字段、property 名称或顶层全局变量。
|
||||
- **公有成员变量**若必须存在，使用 `PascalCase`；但**不推荐外部直接访问公有字段**。
|
||||
- 对外暴露的成员优先使用 **property**：
|
||||
- property 名称使用 `PascalCase`（视为对外 API）。
|
||||
- property 的 `read/write` 指向真实成员（通常为私有 `snake_case_`）。
|
||||
- 示例：
|
||||
|
||||
```tsl
|
||||
type User = class
|
||||
public
|
||||
property UserId read user_id_ write user_id_;
|
||||
private
|
||||
user_id_;
|
||||
end;
|
||||
```
|
||||
|
||||
### 5.3 全局/静态变量
|
||||
|
||||
- 不推荐使用顶层全局/静态可变变量；优先封装到 `unit`/`class` 中，通过函数或 property 访问。
|
||||
- 若必须声明顶层全局/静态变量，使用 `g_snake_case` 前缀显式标识其全局性质，例如 `g_user_cache`、`g_market_state`。
|
||||
- 全局/静态常量仍按常量规则使用 `kPascalCase`。
|
||||
|
||||
### 5.4 布尔变量
|
||||
|
||||
- 使用 `is_ / has_ / can_ / should_` 等前缀表达语义。
|
||||
- 示例：`is_ready`、`has_error`、`can_retry`。
|
||||
|
||||
### 5.5 短名例外
|
||||
|
||||
- 在极小作用域内可用习惯短名：`i`、`j`、`n`、`t` 等。
|
||||
- 作用域一旦扩大，必须改为有含义的名字。
|
||||
|
||||
### 5.6 集合与复数命名（Collections）
|
||||
|
||||
- **数组/列表/可迭代集合**使用复数名词的 `snake_case`：`users`、`order_items`。
|
||||
- 若复数形式不直观或为不可数名词，使用后缀明确类型：`news_list`、`price_items`。
|
||||
- **映射/字典（key→value）**使用 `snake_case` 并加后缀 `_map`，必要时可用 `_by_<key>` 表达键语义：`user_map`、`price_by_symbol`。
|
||||
- **集合/去重集合**使用后缀 `_set`：`user_id_set`、`symbol_set`。
|
||||
|
||||
## 6. 常量命名（Constant Names）
|
||||
|
||||
- **编译期/全局期固定的常量**使用 `kPascalCase`，以 `k` 开头。
|
||||
- 示例：`kDaysInAWeek`、`kAndroid8_0_0`。
|
||||
- 对于**局部 const 但值来自参数/运行时**的变量：
|
||||
- 可用普通变量名 `snake_case`；
|
||||
- 不要用 `k` 前缀误导读者认为其全局固定。
|
||||
|
||||
### 6.1 单元枚举模拟（Unit Enumerations）
|
||||
|
||||
TSL 没有内置 `enum`，推荐使用 `unit` + `const` 在 `interface` 区域模拟枚举集合。
|
||||
|
||||
- `unit` 名称使用 `PascalCase`，建议以 `Enumerations`/`Enums` 结尾表达用途。
|
||||
- 枚举值使用 `const` 定义并放在 `interface` 中；命名优先沿用外部/业务域既有前缀与风格（属于例外场景）。
|
||||
|
||||
示例：
|
||||
|
||||
```tsl
|
||||
unit DocxEnumerations;
|
||||
interface
|
||||
|
||||
// WdAlertLevel
|
||||
const wdAlertsAll = -1;
|
||||
end.
|
||||
```
|
||||
|
||||
## 7. 函数与方法命名（Function Names）
|
||||
|
||||
- 所有**普通**函数/方法（包含 `public`/`private`）均使用 `PascalCase`。
|
||||
- **特殊函数/运算符重载为语法固定名，必须使用全小写**：
|
||||
- 构造/初始化函数：`create`。
|
||||
- 析构/释放函数：`destroy`。
|
||||
- 运算符重载：`operator+()` 等，按语法使用小写 `operator<op>()` 形式。
|
||||
- 示例：`AddTableEntry()`、`DeleteUrl()`、`OpenFileOrDie()`。
|
||||
- **推荐使用 property 语法**对外暴露访问器：property 名 `PascalCase`，`read/write` 绑定成员变量（见类成员章节）。
|
||||
- 不推荐新增显式 getter/setter；仅当 property 无法表达语义时，才使用 getter/setter，命名可与字段同形的 `snake_case`（如 `count()`、`set_count(x)`）。
|
||||
|
||||
## 8. 宏与编译期开关（Macro Names）
|
||||
|
||||
- 能不用宏就不用。
|
||||
- 必须使用时，命名为全大写加下划线，并带项目/业务前缀：
|
||||
- `TSL_ROUND(x)`、`TSL_ENABLE_FOO`。
|
||||
|
||||
## 9. 例外（Exceptions）
|
||||
|
||||
- 当命名需要与外部既有 API/协议保持一致时，可沿用对方风格。
|
||||
- 例如对接 C/C++ 库、历史接口、跨语言互操作代码等。
|
||||
@@ -0,0 +1,62 @@
|
||||
# TSL 工具链与验证命令（模板）
|
||||
|
||||
本文件提供一份**通用占位模板**，用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。
|
||||
|
||||
使用方式：
|
||||
|
||||
- 在具体项目中复制本模板并把占位符替换为真实信息；
|
||||
- 或在项目文档中引用本模板，并在项目内提供对应的 `scripts/*` 统一入口脚本。
|
||||
|
||||
## 1. TSL 工具链
|
||||
|
||||
### 1.1 解释器/编译器（必填）
|
||||
|
||||
- 工具名称：`<tsl/tslcli/内部工具名>`
|
||||
- 可执行命令：
|
||||
- macOS/Linux：`<command>`（例：`tsl` / `tslcli` / `sh scripts/tsl.sh`）
|
||||
- Windows：`<command>`（例：`tsl.exe` / `tslcli.exe` / `powershell -File scripts/tsl.ps1`）
|
||||
- 版本要求：`<固定版本或范围，例如：= 3.2.1 / >=3.2,<4.0>`
|
||||
- 安装方式：`<内部安装包/路径/IDE 自带/CI 镜像等>`
|
||||
- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`（封装参数与环境变量，避免每个任务重复猜测）
|
||||
|
||||
### 1.2 运行环境（按需）
|
||||
|
||||
- 必要环境变量：`<TSL_HOME> <TSL_LIB_PATH> <LICENSE_PATH> ...`
|
||||
- 外部依赖：`<数据库/服务/共享目录/网络权限/账户权限>`
|
||||
- 运行约束：
|
||||
- 是否允许联网：`<yes/no>`
|
||||
- 是否需要许可证/凭证：`<说明如何在本地与 CI 提供；禁止写入仓库>`
|
||||
|
||||
## 2. 验证命令
|
||||
|
||||
> 要求：改动完成后至少能跑通“最小冒烟”；若项目存在测试体系，尽量补到对应层级。
|
||||
|
||||
### 2.1 最小冒烟（必须能跑）
|
||||
|
||||
- macOS/Linux：`<tsl> run <path/to/SmokeTest.tsl> -- <args>`
|
||||
- Windows：`<tsl.exe> run <path\\to\\SmokeTest.tsl> -- <args>`
|
||||
- 或统一入口：
|
||||
- `sh scripts/smoke.sh`
|
||||
- `powershell -File scripts/smoke.ps1`
|
||||
|
||||
### 2.2 单元测试（如有）
|
||||
|
||||
- `sh scripts/test.sh`
|
||||
- 或：`<tsl> test <tests/>`
|
||||
- 或：`<tsl> run <path/to/TestRunner.tsf>`
|
||||
|
||||
### 2.3 静态检查/格式化（如有）
|
||||
|
||||
- `sh scripts/lint.sh`
|
||||
- `sh scripts/format.sh`
|
||||
- 或：`<tsl> check <src/>` / `<tsl> fmt <src/>`
|
||||
|
||||
### 2.4 构建/打包（如有）
|
||||
|
||||
- `sh scripts/build.sh`
|
||||
- 或：`<tsl> build <project-file>`
|
||||
|
||||
### 2.5 失败处理约定（必填）
|
||||
|
||||
- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。
|
||||
- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。
|
||||
Reference in New Issue
Block a user