124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# 代码风格（Code Style）
|
||
|
||
本章节规定 TSL 代码的结构与格式约定。
|
||
|
||
## 1. 文件与组织
|
||
|
||
- 一个文件只做一件事；职责明确。
|
||
- 文件名使用 `PascalCase`，并与文件内唯一的顶层声明同名（语法要求）。扩展名按类型使用 `.tsl`/`.tsf`。
|
||
- 避免循环依赖；公共能力下沉到可复用模块。
|
||
- 同类代码按“对外 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 性能与可测试性
|
||
|
||
- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。
|
||
- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。
|