📝 docs(tsl): rebuild canonical syntax and routing manual
This commit is contained in:
+72
-28
@@ -1,7 +1,17 @@
|
||||
# TSL 代码风格（Code Style）
|
||||
|
||||
文档类型：规范页
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md)
|
||||
|
||||
本章节规定 TSL 代码的结构与格式约定。
|
||||
|
||||
以下出现的 `<TOKEN>`、`<...>`、模板占位和单独标成 `反例 / 不可照写` 的块，只用于说明风格或反例，不等于可直接复制的源码字面量。
|
||||
|
||||
本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法，不等于语法主线里“已验证会编译失败/运行失败”的反向边界；因此页头里的 `是否含已验证反例` 仍保持为 `否`。
|
||||
|
||||
相关文档：
|
||||
|
||||
- 命名规范：`docs/tsl/naming.md`
|
||||
@@ -65,6 +75,8 @@
|
||||
|
||||
- 代码块使用统一的块结构（示例按常见 TSL 写法；若项目语法/约定有差异，以项目现有代码为准）：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
if cond then
|
||||
begin
|
||||
@@ -81,6 +93,8 @@ end
|
||||
- `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
|
||||
- 单语句分支可省略 `begin/end`（保持清晰优先；一旦分支变复杂就回退到块结构）：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
if cond then DoSomething()
|
||||
else DoOther()
|
||||
@@ -100,8 +114,10 @@ else DoOther()
|
||||
- 复杂条件拆分为具名布尔变量或小函数。
|
||||
- 早返回优于深层嵌套：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
if !ok then return err
|
||||
if !ok then return err;
|
||||
// main path
|
||||
```
|
||||
|
||||
@@ -136,6 +152,8 @@ if !ok then return err
|
||||
- 注释使用完整句子，末尾带标点。
|
||||
- 推荐模板（按需裁剪；语言可中英混写）：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
// Summary: 一句话说明做什么（以及关键约束/边界）。
|
||||
// Args:
|
||||
@@ -151,8 +169,21 @@ if !ok then return err
|
||||
- 避免“显而易见注释”：
|
||||
- 尾随注释（写在代码行末）只用于非常短的补充；超过一行时改为写在语句上方，或重构代码提醒意图。
|
||||
|
||||
不推荐这样写：
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
代码块说明：风格反例，不是已验证语法反例。
|
||||
|
||||
```tsl
|
||||
count = count + 1 // bad: obvious
|
||||
count := count + 1; // obvious
|
||||
```
|
||||
|
||||
推荐直接删掉这类显而易见注释：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
count := count + 1;
|
||||
```
|
||||
|
||||
### 3.4 TODO/FIXME
|
||||
@@ -164,8 +195,7 @@ count = count + 1 // bad: obvious
|
||||
## 4. 代码实践（Best Practices）
|
||||
|
||||
> 本节偏“实践建议”（should），用于提升可读性/可测试性；若目标项目有更严格的约束与检查命令，以项目落地的工具链为准（参考
|
||||
> `docs/tsl/toolchain.md`）。如需给自动化/AI 代理配置强约束，可参考
|
||||
> `.agents/tsl/code_quality.md` 与 `.agents/tsl/testing.md`。
|
||||
> `docs/tsl/toolchain.md`）。如果项目对自动化或 AI 代理有额外要求，应把约束直接写进仓库内可见的检查脚本、CI 配置或项目文档，而不是依赖隐藏规范。
|
||||
|
||||
### 4.1 变量与常量
|
||||
|
||||
@@ -174,6 +204,8 @@ count = count + 1 // bad: obvious
|
||||
- 对外 API 优先只读：对外暴露用只读 property（只有 `read`，不写
|
||||
`write`），内部用私有成员保存。
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
type User = class
|
||||
public
|
||||
@@ -196,6 +228,8 @@ end;
|
||||
`Style`（建议紧贴类型名书写）。
|
||||
- 示例（`{Unit.}` 前缀仅用于阅读，不改变类型名）：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
type DocxContext = class
|
||||
public
|
||||
@@ -210,6 +244,8 @@ function RenderParagraph(para_: {DocxML.}Paragraph): void;
|
||||
- 无返回值函数显式标注返回类型为 `void`；`create`/`destroy`
|
||||
作为构造/析构函数不写返回类型。
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
function Func(a: string; b: ClassName): void;
|
||||
```
|
||||
@@ -222,21 +258,29 @@ function Func(a: string; b: ClassName): void;
|
||||
- 输入参数在前；可选配置/选项（如 `*Options`/`*Config`）居中；输出/回调在后。
|
||||
- 避免堆叠多个布尔开关参数；优先收敛到 `*Options`/`*Config`（按需在 `class` 或
|
||||
`unit` 中定义）。
|
||||
- 示例：避免多个布尔开关参数（调用点难以理解 `true/false` 的含义），改为
|
||||
- 示例：避免多个开关参数直接堆在签名里（调用点难以理解各参数含义），改为
|
||||
`*Options`/`*Config`：
|
||||
|
||||
不推荐这样写：
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
代码块说明：风格反例，不是已验证语法反例。
|
||||
|
||||
```tsl
|
||||
// 注：参数类型名按项目实际替换（此处 bool/Any 仅为示例占位）。
|
||||
// bad: 多个 bool 参数在调用点难读、易传错
|
||||
function ExportReport(
|
||||
path: string;
|
||||
data: Any;
|
||||
include_header: bool;
|
||||
compress: bool;
|
||||
dry_run: bool
|
||||
rows: array;
|
||||
include_header;
|
||||
compress;
|
||||
dry_run
|
||||
): void;
|
||||
```
|
||||
|
||||
// good: 将可选开关收敛到 Options（调用点更自解释、后续扩展更稳定）
|
||||
推荐把可选开关收敛到 `Options` / `Config`：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
type ExportOptions = class
|
||||
public
|
||||
property IncludeHeader read include_header_ write include_header_;
|
||||
@@ -248,7 +292,7 @@ private
|
||||
dry_run_;
|
||||
end;
|
||||
|
||||
function ExportReport(path: string; data: Any; options: ExportOptions): void;
|
||||
function ExportReport(path: string; rows: array; options: ExportOptions): void;
|
||||
```
|
||||
|
||||
- 尽量避免超过 5 个参数；必要时封装为对象（`class`/`unit`）。
|
||||
@@ -267,22 +311,22 @@ function ExportReport(path: string; data: Any; options: ExportOptions): void;
|
||||
- 错误信息与日志（允许在库里打日志，但要克制）：
|
||||
- 错误/日志至少包含：**做什么失败** +
|
||||
**关键上下文（脱敏）**，便于定位；避免只有“failed”。
|
||||
- 禁止把 Token/密码/个人数据等敏感信息写入日志、注释或错误信息（参考
|
||||
`.agents/tsl/auth.md`）。
|
||||
- 禁止把 Token、密码、个人数据等敏感信息写入日志、注释或错误信息；如需记录标识，优先记录脱敏后的业务 ID 或可复现的上下文键。
|
||||
- 避免重复记录：同一个错误链路尽量只在**边界层**记录一次（库里记录后，上层通常不再重复打一遍同等级日志）。
|
||||
- 示例：`try/except/end` + 降级（best-effort）：
|
||||
- 注：示例中的 `Any`/`nil`/`LogWarn`/`ReadCacheFromFile`
|
||||
为占位，按项目实际类型与函数替换。
|
||||
- `LoadCacheValue` / `RecordCacheWarning` 代表项目自有函数，重点在结构而不是函数名本身。
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
// 读取可选缓存：失败允许降级为 cache miss（必须可观测，并说明原因）。
|
||||
function ReadOptionalCache(path: string): Any;
|
||||
function ReadOptionalCache(path: string);
|
||||
begin
|
||||
try
|
||||
return ReadCacheFromFile(path)
|
||||
return LoadCacheValue(path)
|
||||
except
|
||||
// best-effort: cache 仅用于提速，失败不应影响主流程
|
||||
LogWarn("ReadOptionalCache failed; fallback to miss. path=" + path)
|
||||
RecordCacheWarning(path)
|
||||
return nil
|
||||
end
|
||||
end;
|
||||
@@ -290,22 +334,22 @@ end;
|
||||
|
||||
### 4.4 性能与可测试性
|
||||
|
||||
- 避免过早优化：先写清晰正确的代码，再用数据（profile/trace/log/基准）定位瓶颈并做最小化改动（参考
|
||||
`.agents/tsl/performance.md`）。
|
||||
- 复杂逻辑要可测试：把“纯计算/解析/规则”与“I/O/环境依赖（文件/网络/DB/全局状态）”分离；I/O 层做薄封装，核心逻辑保持可单测（参考
|
||||
`.agents/tsl/testing.md`）。
|
||||
- 避免过早优化：先写清晰正确的代码，再用项目实际可用的 profile、trace、日志或基准数据定位瓶颈，并做最小化改动。
|
||||
- 复杂逻辑要可测试：把“纯计算/解析/规则”与“I/O/环境依赖（文件/网络/DB/全局状态）”分离；I/O 层做薄封装，核心逻辑保持可单测。
|
||||
- 避免在热路径里做隐式昂贵操作：循环内重复 I/O、重复解析/格式化、无界缓存、隐式复制等；缓存如必须引入，明确生命周期与上限（大小/TTL/清理点）。
|
||||
- 示例：薄 I/O + 厚纯逻辑（便于测试与复用）：
|
||||
- 注：示例中的 `Any`/`ReadAllText` 为占位，按项目实际类型与函数替换。
|
||||
- `LoadConfigText` 代表项目自己的 I/O 边界函数；`ParseConfig` 只负责解析与校验。
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
```tsl
|
||||
// pure: 只做解析/校验，不做 I/O，便于单元测试
|
||||
function ParseConfig(text: string): Any;
|
||||
function ParseConfig(text: string): array;
|
||||
|
||||
// I/O: 只负责读文件与兜底处理，把逻辑交给 ParseConfig
|
||||
function LoadConfig(path: string): Any;
|
||||
function LoadConfig(path: string): array;
|
||||
begin
|
||||
text = ReadAllText(path)
|
||||
text := LoadConfigText(path);
|
||||
return ParseConfig(text)
|
||||
end;
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user