Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: code comments are self-contained — drop internal audit IDs

esengine4e9dfe1a080b
diff --git a/docs/CODE_COMMENTS.md b/docs/CODE_COMMENTS.md
index 07de5c07a..77624ce5e 100644
--- a/docs/CODE_COMMENTS.md
+++ b/docs/CODE_COMMENTS.md
@@ -12,7 +12,8 @@
- **解释 why,不复述 what。** 注释讲"为什么这么写 / 不变量 / 陷阱 / 契约",不要把代码再用英文念一遍。
- **简洁、现在时、完整句子,首字母大写。**
- **不留注释掉的死代码** —— 删就删(git 记得住)。
-- **带出处**:引用审计/设计依据时给标识,如 `audit A17`、`RC12 §E8`、`sceneManager.ts:264`。
+- **自包含**:注释把"为什么"直接讲清楚,**能独立看懂**。
+- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、私有缩写)——代码读者查不到、而且会过时(那些文档常常根本没进仓库)。确需指向长期存在的**已提交**文档时,写**真实路径**,如 `docs/REARCH_EDITOR_REALM.md`;`file.ts:123` 这种可定位的引用可以。
## 1. 文件头 `@file` / `@brief`
@@ -56,10 +57,16 @@
```ts
// The loader keeps running even when the deadline wins the race; release
-// whatever it produces so a post-deadline GL texture doesn't leak (audit A17).
+// whatever it produces so a post-deadline GL texture doesn't leak.
clearTimeout(timer);
```
+反例(**禁止**,注释里塞内部审计代号,读者无从查起):
+
+```ts
+// Release it instead of leaking it (audit A20). // ❌ "A20" 是什么?
+```
+
反例(**禁止**,复述代码):
```ts
@@ -79,10 +86,10 @@ i++;
## 5. TODO / FIXME
-带上下文或标识,不留裸 `// TODO`:
+说清"要做什么 / 为什么",不留裸 `// TODO`,也不要塞内部代号:
```ts
-// TODO(audit A15c): guard stride_ === 0 before the divide.
+// TODO: guard against stride_ === 0 before the divide (lost-context path).
```
## 6. C++ 特例
@@ -108,4 +115,4 @@ i++;
- [ ] 新增/改动的导出 API 有 `/** */`,且讲的是 why/契约而非签名?
- [ ] 内联注释解释的是"为什么",没有复述代码?
- [ ] 没有注释掉的死代码、没有裸 TODO?
-- [ ] 引用审计/设计点时带了标识(`audit A17` / `RC12 §E8` / `file:line`)?
+- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号)?指向文档时用的是已提交文件的真实路径?
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index ac8ccd987..70379ca33 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -141,7 +141,7 @@ export class Assets {
private textureCache_ = new AsyncCache<TextureResult>((result) => {
// A texture whose load finished after its getOrLoad timed out has no
- // owner; release its GL handle so it doesn't leak VRAM (audit A17).
+ // owner; release its GL handle so it doesn't leak VRAM.
requireResourceManager().releaseTexture(result.handle);
});
private textureRefCounts_ = new Map<string, number>();
diff --git a/sdk/src/asset/AsyncCache.ts b/sdk/src/asset/AsyncCache.ts
index d6a5b1440..85664e2fd 100644
--- a/sdk/src/asset/AsyncCache.ts
+++ b/sdk/src/asset/AsyncCache.ts
@@ -20,7 +20,7 @@ export class AsyncCache<T> {
* @param dispose_ Optional releaser for a value whose load finishes AFTER
* its getOrLoad already timed out — the caller got the timeout rejection,
* so that late value has no owner and would otherwise leak (e.g. a GL
- * texture created past the deadline; audit A17). NOT called for
+ * texture created past the deadline). NOT called for
* invalidate()/clearAll(), whose in-flight results still reach the caller.
*/
constructor(private dispose_?: (value: T) => void) {}
@@ -58,7 +58,7 @@ export class AsyncCache<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
// The loader keeps running even when the deadline wins the race. If
// it produces a value after timing out, that value has no owner —
- // release it so it doesn't leak (audit A17).
+ // release it so it doesn't leak.
void loaderPromise.then(
(late) => { if (timedOut) this.disposeAbandoned_(key, late); },
() => { /* loader rejected — nothing to release */ },
diff --git a/sdk/tests/async-cache-leak.test.ts b/sdk/tests/async-cache-leak.test.ts
index 66c9975ca..201ea6435 100644
--- a/sdk/tests/async-cache-leak.test.ts
+++ b/sdk/tests/async-cache-leak.test.ts
@@ -1,6 +1,6 @@
/**
* @file async-cache-leak.test.ts
- * @brief Regression net for audit A17 — when a load times out, the loader
+ * @brief When a load times out, the loader
* keeps running; its late result used to be dropped on the floor (the
* caller already got the timeout rejection), leaking whatever it had
* allocated (e.g. a GL texture = VRAM). AsyncCache now releases such
@@ -11,7 +11,7 @@ import { AsyncCache } from '../src/asset/AsyncCache';
const after = (ms: number) => new Promise((r) => setTimeout(r, ms));
-describe('AsyncCache abandoned-load disposal (A17)', () => {
+describe('AsyncCache abandoned-load disposal', () => {
it('disposes a value whose load finishes AFTER the timeout', async () => {
const disposed: number[] = [];
const cache = new AsyncCache<number>((v) => disposed.push(v));
diff --git a/sdk/tests/plugin-cleanup.test.ts b/sdk/tests/plugin-cleanup.test.ts
index f0739d613..ca1ca564f 100644
--- a/sdk/tests/plugin-cleanup.test.ts
+++ b/sdk/tests/plugin-cleanup.test.ts
@@ -1,6 +1,6 @@
/**
* @file plugin-cleanup.test.ts
- * @brief Regression net for audit A19 — Physics/Spine plugins must release
+ * @brief Physics/Spine plugins must release
* their native module + world listeners on app teardown (App calls
* plugin.cleanup() at shutdown). Before this, `_physics_shutdown` was
* dead code, the spine backends were never disposed, and the
@@ -12,7 +12,7 @@ import { SpineManager } from '../src/spine/SpineManager';
import { SpinePlugin } from '../src/spine/SpinePlugin';
import { PhysicsPlugin } from '../src/physics/PhysicsPlugin';
-describe('SpineManager.dispose (A19)', () => {
+describe('SpineManager.dispose', () => {
it('shuts down every backend and clears all state, idempotently', () => {
const mgr = new SpineManager({} as any, new Map());
const backendA = { shutdown: vi.fn() };
@@ -37,7 +37,7 @@ describe('SpineManager.dispose (A19)', () => {
});
});
-describe('SpinePlugin.cleanup (A19)', () => {
+describe('SpinePlugin.cleanup', () => {
it('unsubscribes the despawn listener and disposes the spine manager', () => {
const plugin = new SpinePlugin();
const unsub = vi.fn();
@@ -63,7 +63,7 @@ describe('SpinePlugin.cleanup (A19)', () => {
});
});
-describe('PhysicsPlugin.cleanup (A19)', () => {
+describe('PhysicsPlugin.cleanup', () => {
it('shuts down the native physics world and nulls the module', () => {
const plugin = new PhysicsPlugin('fake://physics.wasm');
const shutdown = vi.fn();
diff --git a/sdk/tests/scene-load-failure.test.ts b/sdk/tests/scene-load-failure.test.ts
index 6b9350384..50e195379 100644
--- a/sdk/tests/scene-load-failure.test.ts
+++ b/sdk/tests/scene-load-failure.test.ts
@@ -1,11 +1,11 @@
/**
* @file scene-load-failure.test.ts
- * @brief Regression net for the audit's A18 (scene lifecycle robustness):
- * A18a — a load that throws partway must NOT wedge the scene (a retry
- * has to start fresh, not resolve to undefined forever), and any
- * entities spawned before the throw must be cleaned up.
- * A18b — a user `cleanup` callback that throws must NOT abort unload's
- * entity teardown (which would leak the scene's entities).
+ * @brief Scene lifecycle robustness on failure paths:
+ * (1) a load that throws partway must NOT wedge the scene — a retry has
+ * to start fresh (not resolve to undefined forever), and any
+ * entities spawned before the throw must be cleaned up;
+ * (2) a user `cleanup` callback that throws must NOT abort unload's
+ * entity teardown (which would leak the scene's entities).
*/
import { describe, expect, it, beforeEach, vi } from 'vitest';
@@ -76,7 +76,7 @@ function createMockApp() {
};
}
-describe('SceneManager load-failure recovery (A18a)', () => {
+describe('SceneManager load-failure recovery', () => {
let app: ReturnType<typeof createMockApp>;
let manager: SceneManagerState;
@@ -138,7 +138,7 @@ describe('SceneManager load-failure recovery (A18a)', () => {
});
});
-describe('SceneManager unload teardown robustness (A18b)', () => {
+describe('SceneManager unload teardown robustness', () => {
let app: ReturnType<typeof createMockApp>;
let manager: SceneManagerState;