From 151aaa13d0095853d66fee9a877e40dd8db6f4cd Mon Sep 17 00:00:00 2001 From: StarfishC Date: Fri, 12 Dec 2025 17:50:17 +0800 Subject: [PATCH] :tada: init: scaffold tsl playbook --- .agents/auth.md | 33 ++++++++ .agents/code_quality.md | 32 ++++++++ .agents/index.md | 34 +++++++++ .agents/performance.md | 31 ++++++++ .agents/testing.md | 26 +++++++ .gitattributes | 34 +++++++++ README.md | 44 ++++++++++- docs/code_style.md | 123 ++++++++++++++++++++++++++++++ docs/commit_message.md | 161 ++++++++++++++++++++++++++++++++++++++++ docs/naming.md | 151 +++++++++++++++++++++++++++++++++++++ 10 files changed, 667 insertions(+), 2 deletions(-) create mode 100644 .agents/auth.md create mode 100644 .agents/code_quality.md create mode 100644 .agents/index.md create mode 100644 .agents/performance.md create mode 100644 .agents/testing.md create mode 100644 .gitattributes create mode 100644 docs/code_style.md create mode 100644 docs/commit_message.md create mode 100644 docs/naming.md diff --git a/.agents/auth.md b/.agents/auth.md new file mode 100644 index 0000000..5adf24f --- /dev/null +++ b/.agents/auth.md @@ -0,0 +1,33 @@ +# 安全与鉴权（Auth） + +本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。 + +## 1. 基本原则 + +- **最小权限**：只使用完成任务所需的最低权限与最少数据。 +- **默认保守**：不确定是否敏感时按敏感处理。 +- **不扩散秘密**：任何 secret 只在必要范围内出现。 + +## 2. 凭证与敏感信息 + +- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。 +- 如需示例，使用占位符：``、``。 +- 避免把敏感信息打印到标准输出或错误日志。 + +## 3. 鉴权逻辑修改 + +- 修改鉴权/权限控制时必须说明： + - 变更动机 + - 风险评估 + - 兼容性/回滚方案 +- 默认保持旧行为兼容，除非明确要求破坏性变更。 + +## 4. 依赖与第三方 + +- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。 +- 若必须新增，需在 PR 说明理由、替代方案与安全影响。 + +## 5. 审计与合规 + +- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。 +- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。 diff --git a/.agents/code_quality.md b/.agents/code_quality.md new file mode 100644 index 0000000..fed30c9 --- /dev/null +++ b/.agents/code_quality.md @@ -0,0 +1,32 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单。 + +## 1. 总体要求 + +- 遵守 `docs/code_style.md` 与 `docs/naming.md`。 +- 改动聚焦目标；避免“顺手重构”。 +- API 变更要显式说明影响与迁移方式。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/变量。 +- 避免深层嵌套与重复代码。 +- 必要注释解释“为什么”而不是“做什么”。 + +## 3. 错误处理 + +- 错误必须显式处理；禁止静默吞错。 +- 失败路径要可观测（返回/抛出/日志）。 + +## 4. 复杂度与规模 + +- 单函数尽量 ≤ 60 行；超过应说明原因或拆分。 +- 单次 PR 尽量小步提交，便于 review。 + +## 5. Review 清单 + +- 是否有无关改动？ +- 是否有清晰的动机与行为说明？ +- 是否保持模块内风格一致？ +- 是否需要补测试/示例？ diff --git a/.agents/index.md b/.agents/index.md new file mode 100644 index 0000000..1d6a0b3 --- /dev/null +++ b/.agents/index.md @@ -0,0 +1,34 @@ +# .agents 指南索引 + +本目录用于存放 **AI/自动化代理在本仓库内工作时必须遵守的规则**。 +这些规则与 `docs/` 下的人类开发规范并行： + +- `docs/`：给人看的编码/命名/提交规范 +- `.agents/`：给代理看的任务边界、质量与安全要求 + +## 范围 + +- 适用于本仓库所有目录与文件，除非子目录另有更具体的 `.agents/*.md` 覆盖说明。 +- 当 `.agents` 与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## 与开发规范的关系 + +- 代码风格：`docs/code_style.md` +- 命名规范：`docs/naming.md` +- 提交信息：`docs/commit_message.md` diff --git a/.agents/performance.md b/.agents/performance.md new file mode 100644 index 0000000..b76f73c --- /dev/null +++ b/.agents/performance.md @@ -0,0 +1,31 @@ +# 性能（Performance） + +本文件定义代理在做性能相关改动时的准则与检查项。 + +## 1. 目标与度量 + +- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。 +- 没有指标时不要盲目优化；先补充测量或基准。 + +## 2. 处理流程 + +1. 先定位瓶颈（profile/trace/log）。 +2. 再提出最小化改动方案。 +3. 最后用数据验证收益与副作用。 + +## 3. 优化准则 + +- 优先消除算法/结构性问题，再考虑微优化。 +- 避免引入复杂度换取小收益。 +- 性能优化不应牺牲可读性；必要时加注释说明权衡。 + +## 4. 常见风险 + +- 避免重复计算、无界缓存、隐式复制。 +- 注意热路径中的分配与 I/O。 +- 并发优化要考虑正确性与可测试性。 + +## 5. 验证 + +- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。 +- 若无测试体系，至少提供最小可运行的复现脚本/步骤。 diff --git a/.agents/testing.md b/.agents/testing.md new file mode 100644 index 0000000..6e11561 --- /dev/null +++ b/.agents/testing.md @@ -0,0 +1,26 @@ +# 测试（Testing） + +本文件定义代理在改动代码时的测试策略与要求。 + +## 1. 测试层级 + +- **单元测试**：验证函数/模块的独立行为。 +- **集成测试**：验证模块间交互与关键流程。 +- **回归测试**：防止已修复问题复发。 + +## 2. 何时补测试 + +- 新功能必须新增对应测试。 +- 修复 bug 必须先写/补回归用例。 +- 仅当改动纯文档/注释/格式时可不加测试。 + +## 3. 测试可维护性 + +- 一个用例只验证一个行为点。 +- 测试命名清晰，能从名字看出期望。 +- 避免依赖外部不稳定资源；必要时 mock/stub。 + +## 4. 运行与失败处理 + +- 本仓库未来若引入测试命令，需在此补充统一的运行方式。 +- 测试失败时优先定位改动相关原因，不修无关失败。 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..19916ec --- /dev/null +++ b/.gitattributes @@ -0,0 +1,34 @@ +# Ensure all text files use UTF-8 (by convention) and LF line endings. +# Line endings are normalized to LF in the repo and checked out as LF, +# regardless of OS/core.autocrlf settings. + +# Default: detect text automatically, enforce LF on checkout/commit. +* text=auto eol=lf + +# Explicit text types in this repo. +*.tsl text eol=lf +*.tsf text eol=lf +*.md text eol=lf +*.txt text eol=lf +*.json text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.toml text eol=lf +*.ini text eol=lf +*.cfg text eol=lf +*.xml text eol=lf +*.csv text eol=lf +*.sh text eol=lf + +# Binary files (no line-ending conversion). +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.pdf binary +*.zip binary +*.7z binary +*.gz binary +*.tar binary +*.exe binary diff --git a/README.md b/README.md index ac94531..ef75268 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,43 @@ -# tsl-style-guide +# tsl-playbook -tsl代码风格 \ No newline at end of file +TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则合集。 + +## 目标 + +- 让代码**易读、易维护、易演进**。 +- 风格保持一致，减少无意义的差异。 +- 在不影响清晰度的前提下，尽量简洁。 + +## 原则 + +1. **可读性优先**：读代码的时间远大于写代码。 +2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。 +3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。 + +## 适用范围 + +- 本指南适用于所有 TSL 相关仓库与脚本。 +- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。 + +## docs/（开发规范） + +`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。 + +- `docs/code_style.md`：代码结构、格式、`begin/end` 代码块、注释与通用最佳实践。 +- `docs/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。 +- `docs/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。 + +## .agents/（代理规则） + +`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则，与 `docs/` 并行。 + +- `.agents/index.md`：代理规则索引、适用范围与工作原则。 +- `.agents/auth.md`：安全与鉴权边界、敏感信息处理要求。 +- `.agents/performance.md`：性能优化原则、流程与验证要求。 +- `.agents/code_quality.md`：代码质量底线与 review 清单。 +- `.agents/testing.md`：测试策略与何时补测试。 + +## 版本与贡献 + +- 本项目会持续迭代；变更以 PR 形式提交。 +- 新规则需包含动机、示例、迁移建议（如有）。 diff --git a/docs/code_style.md b/docs/code_style.md new file mode 100644 index 0000000..f9d0836 --- /dev/null +++ b/docs/code_style.md @@ -0,0 +1,123 @@ +# 代码风格（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 性能与可测试性 + +- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。 +- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。 diff --git a/docs/commit_message.md b/docs/commit_message.md new file mode 100644 index 0000000..973d6d9 --- /dev/null +++ b/docs/commit_message.md @@ -0,0 +1,161 @@ +# 提交信息规范（Commit Messages） + +提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。 + +## 1. 目标 + +- 让每次提交都能被独立理解。 +- 支持快速定位问题与版本回滚。 +- 可被工具解析（变更日志/发布流程）。 + +## 2. 格式 + +推荐使用以下结构（emoji 可选）： + +``` +:emoji: type(scope): subject + +body + +footer +``` + +- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。 +- `type`：变更类型，必须从 4 的对应表中选取。 +- `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。 +- `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。 +- `body`：可选，说明动机、关键实现、影响面；每行建议 ≤ 72 字符。 +- `footer`：可选，关联任务/缺陷号，或 `BREAKING CHANGE:` 说明不兼容变更。 + +不使用 emoji 时，首行直接写 `type(scope): subject` 即可。 + +## 3. 约定 + +### 3.1 一次提交的边界 + +- 一个提交对应一个**逻辑变更**，而不是一个文件或一个模块。 +- 可以同时修改多个 `unit/class/function`，只要它们属于同一逻辑变更。 +- **允许合并的情况**：联动修改是变更所必需的同步/适配（不一起提会导致编译失败、测试失败或行为不一致）。 + - 例：改了 A 的接口签名，同时更新 B 的调用点。 +- **应当拆分的情况**：改动彼此独立，仅是“顺手优化/无关重构/额外功能”。 + - 例：在修复 A 的 bug 时顺便重构 B 的内部实现。 +- 实用判断： + 1. 这次提交能用一句话概括吗？若需要两句话，考虑拆分。 + 2. 若只回滚其中一部分，系统还能保持正确吗？不能则不拆。 + 3. 每个提交是否都能保持可运行/可构建/测试不更坏？做不到则合并。 + +### 3.2 大模块重构的提交拆分 + +当重构整个模块并影响到其他模块时，建议按“可回滚的小步”拆分提交： + +1. **前置整理**：仅做无行为影响的清理（重命名、抽函数、补注释/类型、补测试）。 +2. **核心重构**：在模块内部做结构调整，尽量保持对外接口不变；必要时加适配层。 +3. **迁移调用方**：逐步把其他模块迁移到新接口/新行为上。 +4. **清理旧接口**：确认无人使用后再删除适配层/旧代码。 + +若重构为破坏性变更，优先采用“两阶段”：先引入新接口并兼容旧接口（deprecated），迁移完成后再删除旧接口。 + +### 3.3 其他约定 + +- `subject` 尽量 ≤ 72 字符；必要时用 `body` 补充细节。 +- `body/footer` 说明“为什么改、影响什么”，而不是复述代码。 + +## 4. 提交类型与 Emoji 对应 + +本仓库采用固定的 `type`/emoji 一一对应关系；使用 emoji 时必须使用对应的那一个，不得错配。 + +| type | emoji（预览 / 代码） | 说明 | +| ----------- | --------------------------------- | ---------------------------- | +| `init` | :tada: `:tada:` | 初始化/首次发布 | +| `feat` | :sparkles: `:sparkles:` | 新功能 | +| `fix` | :bug: `:bug:` | Bug 修复 | +| `perf` | :rocket: `:rocket:` | 性能优化 | +| `refactor` | :recycle: `:recycle:` | 重构（行为不变） | +| `style` | :art: `:art:` | 代码样式/格式（行为不变） | +| `docs` | :memo: `:memo:` | 文档更新 | +| `test` | :white_check_mark: `:white_check_mark:` | 测试新增/修正 | +| `deps` | :package: `:package:` | 依赖更新 | +| `security` | :lock: `:lock:` | 安全修复 | +| `deprecate` | :warning: `:warning:` | 废弃/弃用标记 | +| `remove` | :wastebasket: `:wastebasket:` | 删除功能/代码 | +| `chore` | :wrench: `:wrench:` | 构建/配置/工具/维护性改动 | +| `contrib` | :busts_in_silhouette: `:busts_in_silhouette:` | 贡献者/致谢相关 | +| `release` | :bookmark: `:bookmark:` | 发布/打版本标签 | + +注：`:white_check_mark:` 为补充图例，用于 `test` 类型。 + +如需新增新的 `type`，必须同时补充对应 emoji 与说明。 + +--- + +## 5. 版本号规范（SemVer） + +遵循语义化版本规范。 + +### 5.1 格式 + +```txt +MAJOR.MINOR.PATCH +``` + +### 5.2 字段说明 + +| 字段 | 说明 | 何时递增 | +| --------- | -------- | ------------------ | +| **MAJOR** | 主版本号 | 不兼容的 API 修改 | +| **MINOR** | 次版本号 | 向后兼容的功能新增 | +| **PATCH** | 修订号 | 向后兼容的问题修正 | + +### 5.3 更新规则 + +- **MAJOR（主版本）**：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。 +- **MINOR（次版本）**：新增功能但保持兼容。递增后 PATCH 重置为 0。 +- **PATCH（修订）**：仅修复 bug，不新增功能。 + +### 5.4 示例 + +```txt +1.0.0 # 首个稳定版 +1.1.0 # 新增功能 +1.1.1 # Bug 修复 +2.0.0 # 破坏性变更 +``` + +### 5.5 Pre-release 版本 + +```txt +1.0.0-alpha.1 +1.0.0-beta +1.0.0-rc.1 +1.0.0 +``` + +### 5.6 初始开发阶段 + +```txt +0.1.0 # 初始版本 +0.2.0 # API 未稳定 +1.0.0 # 首个稳定版 +``` + +注意：`0.x.x` 版本可以随时破坏兼容性。 + +--- + +## 6. 示例 + +带 emoji： + +``` +:sparkles: feat(order): add batch cancel api + +support canceling multiple orders in one request; keep old api unchanged. + +Refs: TSL-1234 +``` + +不带 emoji： + +``` +refactor(order): simplify cancel flow +``` diff --git a/docs/naming.md b/docs/naming.md new file mode 100644 index 0000000..bcb8b88 --- /dev/null +++ b/docs/naming.md @@ -0,0 +1,151 @@ +# 命名规范（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`，文件基名需与之同名。 + +命名建议： + +- 基名统一使用 `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_` 表达键语义：`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()` 形式。 +- 示例：`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++ 库、历史接口、跨语言互操作代码等。