Analyze Code Commenter

Add bilingual comments (Traditional Chinese zh-TW + English) to code without modifying original formatting. Uses only block comments (/ ... /`) - never inline comments (`//`).

Workflow

1. Read code - Load target file completely
2. Analyze structure - Identify:

• Core business logic and algorithms
• Class members/methods/properties
• Complex internal logic blocks, functions, and array/object elements

1. Identify logic blocks - Find all logic blocks requiring comments (see Logic Block Requirements below)
2. Generate bilingual comments (Traditional Chinese zh-TW + English) - Apply format rules below
3. Apply changes - Insert comments using edit_file tool

Logic Block Requirements (Required for ALL logic blocks)

> Reference: For detailed logic block comment rules, see rules/comment-format-rules.md. > > 參考：詳細的邏輯區塊註解規範請參閱 rules/comment-format-rules.md。

All logic blocks MUST be commented, including private/non-public internal logic. Comments help future developers understand complex control flow, business rules, and edge case handling.

What are Logic Blocks?

Logic blocks are code sections that implement specific functionality, including but not limited to:

| Type | Examples | |------|----------| | Control flow | if/else, switch/case, try/catch/finally, loop blocks | | Business logic | Data transformation, validation, calculation algorithms | | Conditional branches | Complex conditions with multiple operators | | Nested logic | Nested loops, nested conditionals, callback functions | | Error handling | Exception catching, fallback logic, retry mechanisms | | State management | State transitions, state machine logic | | Data processing | Array operations, filtering, mapping, reducing |

Comment Requirements for Logic Blocks

• ALL logic blocks require comments - No exception for private/internal logic
• Explain WHY, not just WHAT - Focus on business purpose and intent
• Complex conditions need explanation - Document the reasoning behind complex boolean expressions
• Edge cases must be documented - Explain why certain conditions are handled

Examples of Logic Blocks Requiring Comments

typescript
// ❌ Avoid: Complex logic without comments
if (user.isActive && subscription.status === 'active' &&
	(payment.lastPaymentDate > thirtyDaysAgo || payment.isAutoRenew))
{
	// grant access
}

// ✅ Prefer: Complex conditions with explanation (using block comment)
/**
 * 檢查使用者是否有有效訂閱且最近有付款記錄
 * 或啟用自動續訂功能的使用者
 * Check if user has active subscription with recent payment OR auto-renew enabled
 */
if (user.isActive && subscription.status === 'active' &&
	(payment.lastPaymentDate > thirtyDaysAgo || payment.isAutoRenew))
{
	// grant access
}

typescript
// ❌ Avoid: Nested logic blocks without comments
async function processOrder(order)
{
	const validated = validateOrder(order);
	if (validated)
	{
		const inventory = await checkInventory(order.items);
		if (inventory.available)
		{
			await reserveInventory(order.items);
			if (order.payment.method === 'card')
			{
				// process payment
			}
		}
	}
}

// ✅ Prefer: Each logic block explained with block comments
async function processOrder(order)
{
	/**
	 * 驗證訂單資料格式與必填欄位
	 * Validate order data format and required fields
	 */
	const validated = validateOrder(order);
	if (validated)
	{
		/**
		 * 檢查庫存是否足夠
		 * Check if inventory is sufficient
		 */
		const inventory = await checkInventory(order.items);
		if (inventory.available)
		{
			/**
			 * 預留庫存以防止超賣
			 * Reserve inventory to prevent overselling
			 */
			await reserveInventory(order.items);
			/**
			 * 信用卡支付需要額外驗證
			 * Card payments require additional verification
			 */
			if (order.payment.method === 'card')
			{
				// process payment
			}
		}
	}
}

Priority for Logic Block Comments

1. High Priority - Complex nested logic (3+ levels), business rules, critical paths
2. Medium Priority - Conditional branches, loop logic, error handling
3. Low Priority - Simple one-line conditions, straightforward logic

Bilingual Comment Format Rules

> Reference: For detailed bilingual comment format specifications, see rules/comment-format-rules.md. > > 參考：詳細的雙語註解格式規範請參閱 rules/comment-format-rules.md。

All Members Use Block Comments (Required)

All members must use block comments (/ ... /`), NOT inline comments (`// ...`).

The format depends on how much explanation is needed:

• Simple/brief explanation: Use single-line block comment /** 說明 / Description */
• Detailed explanation or long comment (e.g., bilingual translation makes comment longer): Use multi-line block comment /** ... */

Member Types Requiring Block Comments

| Category | Examples | |----------|----------| | Type definitions | enum members, interface members, type members | | Class members | Properties, methods, constructors | | Function members | Parameters, return values | | Variable declarations | const, let, var with assignment | | Object members | Object properties, return statement members |

Core Principles

| Item | Rule | |------|------| | Comment Type | MUST use block comments (/ ... /`), NEVER inline comments (`//`) | | Position | Each member gets its own block comment, placed above the member | | Comment Length | Brief explanation: single-line block /** 說明 / Description */<br>Detailed or long explanation: multi-line block /** ... */ | | Bilingual Format | Two formats allowed:<br>1. Chinese first, English translation after (separated by /)<br>2. Chinese above, English translation below |

Applicable Scope (Full List)

• enum members
• interface members
• type members
• class properties and methods
• Function parameters and return values
• Variable declarations (const/let/var)
• Object properties (including return statement members)
• Object shorthand properties

Wrong Format vs Correct Format

> Reference: For correct comment format examples, see rules/comment-format-rules.md. > > 參考：正確註解格式範例請參閱 rules/comment-format-rules.md。

Wrong Format (Using Inline Comments)

typescript
// ❌ Using inline comments for members (WRONG)
export interface IOptionsForMap<T>
{
	getKey?,    // 取得分組鍵的函式
	init?,      // 初始化 Map 的函式
}

const config = loadConfig();    // 載入配置
return {
	cwd,        // 當前工作目錄
	modules,    // 找到的模組
}

Correct Format (Using Block Comments)

typescript
// ✅ Using block comments for members (CORRECT)
export interface IOptionsForMap<T>
{
	/**
	 * 取得分組鍵的函式 / Function to get grouping key
	 *
	 * @param item - 要分組的元素 / Element to group
	 * @param index - 元素在陣列中的索引 / Index of element in array
	 * @param arr - 陣列本身 / Array itself
	 */
	getKey?(item: T, index: number, arr: T[]): any

	/** 初始化 Map 的函式 / Function to initialize Map */
	init?(): Map<any, T[]>,
}

/** 載入應用程式配置 / Load application configuration */
const config = loadConfig();

return {
	/** 當前工作目錄 / Current working directory */
	cwd,
	/** 找到的模組陣列 / Array of found modules */
	modules,
}

Wrong Format: Using @property in Interface/Type JSDoc

> Reference: For interface member comment rules, see rules/comment-format-rules.md. > > 參考：Interface 成員註解規則請參閱 rules/comment-format-rules.md。

DO NOT use @property tags in Interface or Type JSDoc to describe members. Instead, add comments directly above each member:

typescript
// ❌ Wrong: Using @property in interface JSDoc to describe members
/**
 * Tool configuration interface
 *
 * @property description - Description
 * @property shortDescription - Short description
 * @property args - Arguments
 */
interface I_AriseToolsConfigEntry {
	description?: string;
	shortDescription: string;
	args: unknown;
}

// ✅ Correct: Add comments directly above each member
interface I_AriseToolsConfigEntry
{
	/** Description */
	description?: string;
	/** Short description */
	shortDescription: string;
	/** Arguments */
	args: unknown;
}

Reasons:

• @property tags require extra maintenance and can become out of sync with actual members
• Member comments are more intuitive and IDE can properly recognize them for IntelliSense
• Follows the "each member gets its own comment" principle

Common Error: Incorrect Block Comment Formatting

> Reference: For block comment formatting rules, see rules/comment-format-rules.md. > > 參考：區塊註解排版規則請參閱 rules/comment-format-rules.md。

常見錯誤：將單行註解轉換為區塊註解時的排版錯誤

當將單行註解轉換為區塊註解，或修正多個單行區塊註解時，容易發生以下排版錯誤：

typescript
// ❌ 錯誤：開頭 `/**` 與第一行文字同行，導致縮排混亂
/** 如果是 optional 類型，遞迴處理其內部類型
	 * If it's an optional type, recursively process its inner type
	 */

// ❌ 錯誤：多個單行區塊註解合併時縮排錯誤
/** 驗證訂單資料格式與必填欄位
	 * Validate order data format and required fields
	 */

// ❌ 錯誤：單行區塊註解合併或單行轉多行時錯誤
/** 驗證訂單資料格式與必填欄位
	 * Validate order data format and required fields */

typescript
// ✅ 正確：開頭 `/**` 獨立一行，後續行正確對齊
/**
 * 如果是 optional 類型，遞迴處理其內部類型
 * If it's an optional type, recursively process its inner type
 */

// ✅ 正確：多個單行區塊註解合併後格式正確
/**
 * 驗證訂單資料格式與必填欄位
 * Validate order data format and required fields
 */

錯誤原因 / Error Cause:

• 將單行註解 /** 文字 */ 直接轉換為多行時，未將開頭 /** 獨立一行
• 使用 Tab 縮排時，後續行的 * 號未正確對齊
• 合併多個單行區塊註解時，未重新調整縮排格式

解決方法 / Solution:

• 開頭 /** 必須獨立一行
• 每行內容前需加 * 並正確對齊
• 結尾 */ 與開頭 /** 對齊

Common Error: Using Inline Comments for Section Separators

> Reference: For section separator rules, see rules/comment-format-rules.md. > > 參考：分隔線註解規則請參閱 rules/comment-format-rules.md。

常見錯誤：使用行內註解作為分隔線

即使是分隔線類型的註解，也必須使用區塊註解，不得使用行內註解：

typescript
// ❌ 錯誤：使用行內註解作為分隔線
// ==================== Zod Schema 工廠函數 ====================

typescript
// ✅ 正確：使用單行區塊註解作為分隔線
/** ==================== Zod Schema 工廠函數 ==================== */

// ✅ 正確：使用區塊註解作為分隔線
/**
 * ==================== Zod Schema 工廠函數 ====================
 */

錯誤原因 / Error Cause:

• 誤以為分隔線只是視覺分隔，不需要遵循區塊註解規則
• 從舊代碼複製時未轉換格式

解決方法 / Solution:

• 所有註解（包含分隔線）都必須使用 /** ... */ 格式
• 分隔線註解可使用單行區塊註解：/** ==================== 標題 ==================== */

Single-line vs Multi-line Block Comments

> Reference: For single-line vs multi-line comment format rules, see rules/comment-format-rules.md. > > 參考：單行與多行區塊註解格式規則請參閱 rules/comment-format-rules.md。

The choice depends on how much explanation is needed (not code complexity).

> Preserve Existing Style: > - If existing comment is already using single-line or multi-line format correctly, do NOT change it > - Both formats are valid bilingual styles: > - Single-line: /** 說明 / Description */ > - Multi-line: /** 說明 * Description */ > - Only adjust when the format violates the rules (e.g., using inline comments instead of block comments, or single-line comment is too long for readability)

Single-line Block Comment

Use when the explanation is brief:

typescript
/** 是否成功 / Whether successful */
const isActive = true;

/** 使用者名稱 / User name */
userName: string;

/** 取得列表 / Get list */
getItems(): Item[];

Multi-line Block Comment

Use when detailed explanation is needed OR the comment is long (e.g., bilingual translation makes it longer):

typescript
/**
 * 取得分組鍵的函式
 * Function to get grouping key
 *
 * @param item - 要分組的元素 / Item to be grouped
 * @param index - 元素在陣列中的索引 / Index in array
 * @param arr - 陣列本身 / The array itself
 */
getKey?(item: T, index: number, arr: T[]): any

/**
 * 解析 URL 查詢參數為鍵值對象
 * Parse URL query string into key-value object
 *
 * 處理步驟：
 * 1. 取得目前的搜尋參數
 * 2. 轉換為鍵值對象
 * 3. 返回結果
 */
const queryParams = new URLSearchParams(window.location.search);

JSDoc (methods/classes/properties)

> Reference: For JSDoc format rules and JSDoc tag bilingual format, see rules/comment-format-rules.md. > > 參考：JSDoc 格式規範與 JSDoc 標籤雙語格式請參閱 rules/comment-format-rules.md。

typescript
/**
 * 繁體中文說明
 * English Description
 *
 * 詳細解釋「為什麼」而非「做什麼」。未來修改或除錯時可快速理解代碼意圖。
 * Explain "why" not just "what". Helps future self or others quickly understand the code's intent during maintenance or debugging.
 *
 * @param {type} name - 參數說明 / Parameter description
 * @returns {type} 返回值說明 / Return description
 */

Logic Block Comments

> Reference: For logic block comment placement rules, see rules/comment-format-rules.md. > > 參考：邏輯區塊註解放置規則請參閱 rules/comment-format-rules.md。

For logic blocks (if/else, loops, try/catch, etc.), use block comments above the block:

typescript
/** 檢查使用者權限 / Check user permissions */
if (user.hasAccess)
{
	// logic
}

/** 遍历所有项目并处理 / Iterate through all items and process */
for (const item of items)
{
	// logic
}

/** 尝试保存数据，失败时回滚 / Attempt to save data, rollback on failure */
try
{
	// logic
}
catch (error)
{
	// error handling
}

Multiple Single-line Block Comments Rule

> Reference: For multiple single-line comment rules, see rules/comment-format-rules.md. > > 參考：禁止多個單行註解規則請參閱 rules/comment-format-rules.md。

NEVER use multiple single-line block comments for the same code element. Merge them into one multi-line block comment.

typescript
// ❌ Avoid: Multiple single-line block comments (WRONG)
/** 驗證訂單資料格式與必填欄位 */
/** Validate order data format and required fields */
const validated = validateOrder(order);

// ✅ Correct: Merge into single multi-line block comment
/**
 * 驗證訂單資料格式與必填欄位
 * Validate order data format and required fields
 */
const validated = validateOrder(order);

Multiple Logic Blocks Rule

When adding comments to 3 or more consecutive logic blocks, use multi-line block comment:

typescript
/**
 * 逻辑说明一 / Logic description one
 *
 * 逻辑说明二 / Logic description two
 *
 * 逻辑说明三 / Logic description three
 */

Logic Comments Placement (Internal Implementation Details)

Core Principle: Comments about implementation logic should be placed near the code logic, not in JSDoc documentation. Only document what is helpful for callers in JSDoc.

| Location | What to Document | |----------|------------------| | JSDoc (function/class level) | API usage, parameters, return values, public contracts, side effects visible to callers | | Logic block (inside function) | Internal implementation reasoning, specific business rules, why this approach was chosen, edge case handling |

Rationale:

• JSDoc is for external consumers/callers - it describes the "contract"
• Internal logic comments are for maintainers - they explain "why" the code does what it does internally
• Placing logic comments near the code helps future developers understand the implementation without jumping between documentation and code

Examples:

typescript
// ❌ Avoid: Putting internal logic explanations in JSDoc
/**
 * Process user data
 *
 * 1. Validates input
 * 2. Checks cache
 * 3. Fetches from database if not cached
 *
 * @param userId - User identifier
 * @returns Processed user data
 */
function getUserData(userId: string): UserData {
    // ... implementation
}

// ✅ Prefer: JSDoc for callers, logic comments near code
/**
 * 取得使用者資料
 * Get user data
 *
 * @param userId - 使用者識別碼 / User identifier
 * @returns 使用者資料 / User data
 */
function getUserData(userId: string): UserData {
    /** 檢查快取是否已有資料 / Check if data exists in cache */
    const cached = cache.get(userId);
    if (cached) {
        return cached;
    }

    /**
     * 資料不在快取中，需從資料庫取得
     * Data not in cache, need to fetch from database
     *
     * 特定業務規則：因為使用者可能被停用，所以需要檢查狀態
     * Specific business rule: need to check status because user may be disabled
     */
    const user = database.find(userId);
    if (user && user.status === 'active') {
        cache.set(userId, user);
    }

    return user;
}

typescript
// ✅ Good: Important business logic in BOTH JSDoc AND near code
// When logic affects the API contract, document it in JSDoc for callers
// 同時在 JSDoc 和程式碼區塊中說明重要的業務邏輯

/**
 * 檢查使用者是否有權存取資源
 * Check if user has permission to access resource
 *
 * 權限判斷條件 / Permission check conditions:
 * 1. 使用者必須處於啟用狀態 / User must be active
 * 2. 必須有專業版訂閱 / Must have Pro subscription
 * 3. 資源為本人建立 或 資源為公開 / Resource created by user OR resource is public
 *
 * @param user - 使用者物件 / User object
 * @param resource - 資源物件 / Resource object
 * @returns 是否允許存取 / Whether access is allowed
 */
function canAccess(user, resource) {
    /**
     * 執行權限檢查 / Perform permission check
     *
     * 判斷邏輯：/ Logic:
     * - 使用者狀態是否啟用 / Check if user is active
     * - 訂閱類型是否為 Pro / Check if subscription is Pro
     * - 資源是否為本人建立或是公開資源 / Check if resource is created by user or public
     */
    return user.isActive && user.subscription === 'pro' &&
        (resource.createdBy === user.id || resource.isPublic);
}

Note 說明: 當邏輯影響 API 合約（如權限判斷條件、驗證規則）時，應同時在 JSDoc 中說明，讓呼叫者了解行為。若邏輯僅是內部實現細節（如效能優化、内部演算法），則只需在程式碼區塊內說明。

JSDoc vs Logic Block Responsibility Separation (Preventing Information Redundancy)

> Reference: For JSDoc vs logic block responsibility separation rules, see rules/comment-format-rules.md. > > 參考：JSDoc 與邏輯區塊職責分離規則請參閱 rules/comment-format-rules.md。

Core Principle / 核心原則： JSDoc describes "contract/intent", logic blocks describe "implementation details".

| 位置 / Location | 應包含 / Should Include | 不應包含 / Should NOT Include | |----------------|------------------------|------------------------------| | JSDoc | 函式用途、設計邏輯、為什麼這樣設計 / Function purpose, design logic, why this design | 具體如何實現、程式碼語法細節 / How to implement, code syntax details | | 邏輯區塊 / Logic Block | 具體實作邏輯、技術細節（as any、運算子等）/ Specific implementation logic, technical details (as any, operators, etc.) | 為什麼要這樣設計 / Why this design |

Error Example / 錯誤示範（資訊冗餘）：

typescript
/**
 * 處理資料（錯誤：將實作細節放在 JSDoc）
 * Process data (wrong: implementation details in JSDoc)
 *
 * 使用短路運算實現：(condition && value) || default  ← ❌ 冗餘
 */
function process(result) {
  /** 短路運算：(condition && value) || default */  ← ✅ 正確位置
  return condition && value || [];
}

Correct Example / 正確範例：

typescript
/**
 * 從結果中取得舊版插件名稱
 * Get legacy plugin names from result
 *
 * 邏輯說明 / Logic description:
 * 1. 首先檢查 LEGACY_PLUGIN_NAME 是否與 PLUGIN_NAME 不同
 *    First check if LEGACY_PLUGIN_NAME is different from PLUGIN_NAME
 * 2. 只有當兩者不同時，才有意義區分「舊版插件」
 *    Only when the two are different does it make sense to distinguish "legacy plugin"
 */
function getLegacyPluginNamesFromResult(result) {
    /**
     * 條件判斷：確保新舊插件名稱確實不同
     * Condition check: ensure legacy and current plugin names are actually different
     *
     * 使用 `as any` 繞過 TypeScript 推導
     * 因為 TS 知道這兩個 const 永遠不同，但 runtime 可能會變化
     *
     * Uses `as any` to bypass TypeScript inference
     * Because TS knows these two consts are always different, but runtime may change
     *
     * 短路運算實現 / Short-circuit evaluation implementation:
     * (condition && value) || default
     * - 當 condition 為 true，回傳 value / When condition is true, return value
     * - 當 condition 為 false，回傳 [] / When condition is false, return []
     */
    return (LEGACY_PLUGIN_NAME !== PLUGIN_NAME as any) && result[LEGACY_PLUGIN_NAME] || [];
}

Checklist / 檢查清單：

• ] JSDoc 中是否包含「如何實現」的語法細節？（如短路運算、as any）

Does JSDoc contain "how to implement" syntax details? (e.g., short-circuit evaluation, as any)

• ] 邏輯區塊內的註解是否僅描述「實作」，而非包含「設計意圖」？

Do logic block comments only describe "implementation", not include "design intent"?

JSDoc Avoid Redundant Descriptions

> Reference: For JSDoc redundant description rules, see rules/comment-format-rules.md. > > 參考：JSDoc 避免冗餘描述規則請參閱 rules/comment-format-rules.md。

不需要「標題 + 與標題相同意思的描述」，兩段意思相同的註解只保留一組完整的描述即可。 No need for "title + description with the same meaning" - keep only one complete set of descriptions if they mean the same thing.

❌ Wrong / 錯誤（意思重複）：

typescript
/**
 * 處理資料
 * Process data
 *
 * 此函數用於處理資料
 * This function is used to process data
 */

> 標題「處理資料」與描述「此函數用於處理資料」意思完全相同，屬於冗餘。 > Title "處理資料" and description "此函數用於處理資料" mean exactly the same thing - redundant.

✅ Correct / 正確（選擇一組完整的描述）：

typescript
/**
 * 此函數用於處理資料
 * This function is used to process data
 *
 * 設計邏輯 / Design logic: ...
 */

Exception / 例外情況：

當 JSDoc 需要包含多個獨立說明區塊時，可以使用簡短標題： When JSDoc needs to contain multiple independent description blocks, you can use brief titles:

typescript
/**
 * 工具函式集合
 * Utility functions collection
 *
 * 錯誤處理工具：
 * Error handling utilities:
 * ...
 *
 * 資料轉換工具：
 * Data transformation utilities:
 * ...
 */

Preserve Original Style

> Reference: For preserving original comment style rules, see rules/comment-format-rules.md. > > 參考：保留原始註解風格規則請參閱 rules/comment-format-rules.md。

If original comments use block style /** ... */, preserve format and add English translation. Do not convert to inline comments.

Do NOT change between single-line and multi-line formats - both are valid bilingual styles:

• Single-line: /** 說明 / Description */
• Multi-line: /** 說明 * Description */

Only convert when the format violates the rules (e.g., using inline comments instead of block comments, or single-line comment is too long for readability)

Critical Constraints

> Reference: For detailed critical constraints and comment rules, see rules/comment-format-rules.md. > > 參考：詳細的重要約束與註解規則請參閱 rules/comment-format-rules.md。

• ALWAYS use block comments (/ ... /`) - Never use inline comments (//) for any code
• NEVER modify existing code formatting (indentation, line breaks, spaces)
• NEVER delete old commented-out code (e.g., // old code..., /* old code... */, or /** @deprecated */)
• NEVER convert existing CJK characters to Traditional Chinese - only use Traditional Chinese in NEW comments
• NEVER write "English + English" as fake bilingual comments - each comment pair MUST contain Traditional Chinese followed by English, not two English lines
• For key terms, add English in parentheses: 快取 (Cache), 佇列 (Queue), 遞迴 (Recursion)

Exception: Inline Comments in JSDoc @example Blocks

> Reference: For JSDoc @example inline comment exception rules, see rules/comment-format-rules.md. > > 參考：JSDoc @example 行內註解例外規則請參閱 rules/comment-format-rules.md。

Inline comments (//) are ALLOWED within JSDoc @example code blocks. This is because:

1. Example comments are for documentation display purposes, not executable code
2. Used to show expected output or behavior (e.g., console.log(x); // Output: 3)
3. System limitation: Cannot use nested block comments inside examples

typescript
/**
 * @example
 * ```typescript
 * // Modifying cloned styles does not affect the original
 * cloned._styles.push({ open: '\\x1b[34m', close: '\\x1b[39m', closeRe: /\\x1b[39m/ });
 * console.log(source._styles.length); // 2 (original unchanged)
 * console.log(cloned._styles.length); // 3 (cloned modified)
 * ```
 */

Special Directives Placement (e.g., // @ts-ignore)

> Reference: For special directives placement rules, see rules/comment-format-rules.md. > > 參考：特殊指令放置規則請參閱 rules/comment-format-rules.md。

核心原則：特殊指令註解必須緊鄰目標代碼，區塊註解應放在特殊指令之前。

當代碼中包含特殊指令註解（如 // @ts-ignore、// @ts-expect-error、// eslint-disable 等）時，區塊註解必須放在特殊指令之前，而非之後。

錯誤範例 / Wrong Example

typescript
// ❌ 錯誤：特殊指令放在區塊註解之前
// @ts-ignore
/**
 * 將 Console2 類別指派給原型屬性以便於型別檢查
 * Assign Console2 class to prototype property for type checking convenience
 */
Console2.prototype.Console = Console2

正確範例 / Correct Example

typescript
// ✅ 正確：區塊註解放在特殊指令之前
/**
 * 將 Console2 類別指派給原型屬性以便於型別檢查
 * Assign Console2 class to prototype property for type checking convenience
 */
// @ts-ignore
Console2.prototype.Console = Console2

原因說明 / Reason

• 特殊指令（如 // @ts-ignore）需要緊鄰目標代碼才能生效
• 區塊註解是說明性質，應放在特殊指令之前
• 這樣可以確保特殊指令正確作用於目標代碼，同時保持註解的可讀性

常見特殊指令 / Common Special Directives

| 指令 / Directive | 用途 / Purpose | |-----------------|----------------| | // @ts-ignore | 忽略 TypeScript 型別檢查錯誤 / Ignore TypeScript type checking errors | | // @ts-expect-error | 預期會有型別錯誤（用於測試）/ Expect type errors (for testing) | | // eslint-disable | 停用 ESLint 規則 / Disable ESLint rules | | // eslint-disable-next-line | 停用下一行的 ESLint 規則 / Disable ESLint rules for next line | | // @ts-nocheck | 停用整個檔案的 TypeScript 檢查 / Disable TypeScript checking for entire file |

Preserve Technical Terms (DO Not Delete)

> Reference: For technical term preservation rules, see rules/comment-format-rules.md. > > 參考：技術術語保留規則請參閱 rules/comment-format-rules.md。

核心原則：技術術語不得刪除。

當更新註解時，必須保留以下類型（但不限於）的原始術語。可新增翻譯或解釋，但「不得」以「更好描述」為由刪除原始術語。

| 術語類型 / Term Type | 範例 / Examples | |---------------------|----------------| | TypeScript/JavaScript 官方術語 | Non-Null Assertion Operator (!)、Union Type、Type Guard、Generics、Decorator | | 演算法名稱 | Dijkstra、Binary Search、Quick Sort、Dynamic Programming、Backtracking | | 設計模式名稱 | Singleton、Factory、Observer、Strategy、Adapter、Decorator | | 資料結構名稱 | Linked List、Hash Map、Binary Tree、Stack、Queue、Heap | | 程式設計概念 | Recursion、Memoization、Currying、Polymorphism、Encapsulation |

typescript
// ✅ 正確：保留原始術語並添加翻譯
/**
 * 使用 Non-Null Assertion Operator (!) 確保值不為 null
 * Uses Non-Null Assertion Operator (!) to ensure value is not null
 */
const value = nullableValue!;

/**
 * 實作 Factory Pattern 建立不同類型的產品
 * Implements Factory Pattern to create different types of products
 */
function createProduct(type: string) { ... }

/**
 * 使用 Dijkstra's Algorithm 找最短路徑
 * Uses Dijkstra's Algorithm to find shortest path
 */
function findShortestPath(graph) { ... }

// ❌ 錯誤：刪除原始術語
/**
 * 使用驚嘆號確保值不為空
 * Uses exclamation mark to ensure value is not empty
 */
const value = nullableValue!;

/**
 * 建立產品
 * Create products
 */
function createProduct(type: string) { ... }

/**
 * 找最短路徑
 * Find shortest path
 */
function findShortestPath(graph) { ... }

新增翻譯時的正確做法：

• ✅ 保留原始術語：Union Type（聯合類型）
• ✅ 添加說明：TypeScript 的 Union Type（聯合類型）允許...
• ❌ 刪除原始術語：此函式接受多種可能的類型（不應刪除 Union Type）

This is a hard constraint - technical terms provide searchable, referenceable information and represent established vocabulary in the field.

Preserve Non-Chinese and Non-English Comments

核心原則：若原始註解包含中文與英文以外的語言，請保留該語言的註解。

當遇到包含其他語言（包含但不限於日語、韓語、德語、法語等）的原始註解時，應保留該語言內容，並在其後添加繁體中文與英文的雙語註解。

| 情境 / Scenario | 處理方式 / Handling | |-----------------|---------------------| | 原始註解為純其他語言（如日語） | 保留日語，新增繁體中文與英文翻譯 | | 任意多語言註解（例如：中、英、日） | 保留所有語言，維持原有結構；檢查是否缺少中英註解，若缺少則補充 | | 原始註解僅為中英雙語 | 遵循標準雙語註解格式 |

範例 / Examples:

範例 1：日語註解保留

typescript
// 原始：
/**
 * パスワードを暗号化する
 */
function encryptPassword(password: string) { ... }

// ❌ 錯誤結果（日語遺失，僅保留中英雙語）：
/**
 * 密碼加密函式
 * Password encryption function
 */
function encryptPassword(password: string) { ... }

// ✅ 正確結果（保留原始日語並添加中英雙語）：
/**
 * パスワードを暗号化する
 * 密碼加密函式
 * Password encryption function
 */
function encryptPassword(password: string) { ... }

範例 2：韓語註解保留

typescript
// 原始：
/**
 * 데이터베이스 연결 설정
 */
const dbConfig = { ... };

// ✅ 正確結果（保留原始韓語並添加中英雙語）：
/**
 * 데이터베이스 연결 설정
 * 資料庫連線設定
 * Database connection configuration
 */
const dbConfig = { ... };

範例 3：多語言註解補充中英

typescript
// 原始（已有日語 + 英語，缺少中文）：
/**
 * ユーザーデータを処理する
 * Process user data
 */
function processUserData(user: User) { ... }

// ✅ 正確結果（保留所有語言，補充缺少的中文）：
/**
 * ユーザーデータを処理する
 * 處理使用者資料
 * Process user data
 */
function processUserData(user: User) { ... }

Identify Non-semantic Naming Conventions

> Reference: For non-semantic naming convention rules, see rules/comment-format-rules.md. > > 參考：無語義命名慣例識別規則請參閱 rules/comment-format-rules.md。

核心原則：當程式碼中存在無特殊含義的命名慣例時，註解應謹慎處理。

某些命名慣例（如 Lazy、Helper、Util）可能被用作組織程式碼的慣用方式，而非表達特定的技術意涵。註解時應：

• 不為其添加原本沒有的意義
• 如果有必要則明確標記為「命名慣例」或「無特殊含義」
• 或者直接忽略，視為不存在（避免多餘無意義註解）

如何判斷無特殊含義

| 命名 / Naming | 判斷方式 / How to Check | |---------------|------------------------| | Lazy | 檢查是否有延遲執行邏輯（Promise、callback、getter、計算屬性）。若無，則為命名慣例 | | Helper / Util | 檢查是否僅是工具函式集合。若無特定領域抽象，則為命名慣例 | | Base / Core | 檢查是否有繼承或組合關係。若僅是組織結構，則為命名慣例 | | Impl | 檢查是否有介面/抽象類。若無，則為命名慣例 |

若無對應的設計模式或技術含義，則視為命名慣例。

正確範例

typescript
/**
 * 配置獲取值型別
 * Config getter value type
 *
 * @note Lazy 為命名慣例，無「延遲/惰性」意涵
 * @note Lazy is a naming convention, no "lazy/惰性" meaning
 */
export type ILazyConfigGetterValue = ...

/**
 * 工具函式集合
 * Utility functions collection
 *
 * @note Helper 為命名慣例，僅表示此模組為工具函式集
 * @note Helper is a naming convention, only indicates this module is a utility collection
 */
export class StringHelper { ... }

錯誤範例

typescript
// ❌ 錯誤：為命名慣例添加原本不存在的意義
/**
 * 懶惰載入配置
 * Lazy load configuration
 *
 * 此類採用延遲初始化模式...
 * This class uses lazy initialization pattern...
 */
// 實際程式碼並無延遲執行邏輯

export type ILazyConfigGetterValue = ...

// ✅ 正確：若無法判斷，可標註為「可能相關，未驗證」
/**
 * 配置獲取值型別
 * Config getter value type
 *
 * @note 命名可能與 Lazy Loading 相關，未驗證
 * @note Naming may be related to Lazy Loading, unverified
 */
export type ILazyConfigGetterValue = ...

###

Comment Update Rules (Preventing Comment Update Rules)

> Reference: For detailed comment update rules, see rules/comment-format-rules.md. > > 參考：詳細的註解更新規則請參閱 rules/comment-format-rules.md。

When updating existing comments, follow these additional rules to preserve valuable technical information.

Rule 1: Preserve Original Error Information

When code contains error codes, error messages, or other original technical information, only add translation, do NOT delete.

typescript
// ✅ Correct - Preserve original error code and message
/**
 * 工具建立函式（避免 TypeScript 推導錯誤）
 * Tool creation function (avoids TypeScript inference errors)
 *
 * > error TS2742: 原始錯誤訊息 (保留不刪)
 */

// ❌ Wrong - Delete original error information
/**
 * 工具建立函式
 * Tool creation function
 */

Rule 2: Issue Links Must Verify Relevance

Before adding Issue/document links, must confirm the content is actually related.

新增條件：
1. 已閱讀 Issue 內容
2. 確認與代碼/問題/邏輯/意圖有直接關聯
3. 無法確認時 → 不新增，或標註「可能相關，未驗證」

Add conditions:
1. Have read the Issue content
2. Confirm direct relevance to code/problem/logic/intent
3. If unable to verify → Do not add, or mark as "possibly related, unverified"

Rule 3: Value of Error Messages

| 資訊類型 / Information Type | 價值 / Value | |---------------------------|-------------| | 錯誤碼 (TS2742) | 可搜尋、可引用 / Searchable, can be referenced | | 完整路徑 (.pnpm/zod@4.1.8/...) | 有助於定位問題 / Helps locate the problem | | 錯誤描述 | 社群已知問題的驗證 / Verification of known community issues |

這些都不應被視為「冗餘」而刪除。 These should NOT be deleted as "redundant".

Rule 4: Comment Update Checklist

每次更新他人註解前，確認： Before updating others' comments, verify:

• ] 原始註解的技術資訊是否保留？（錯誤碼、版本號、檔案路徑等）

Is original technical information preserved? (error codes, version numbers, file paths, etc.)

• ] 新增的連結是否已驗證相關性？

Have added links been verified for relevance?

• ] 是否與 代碼/問題/邏輯/意圖 相關？

Is it related to code/problem/logic/intent?

Bilingual Comment Validation

Every bilingual comment MUST use block comment format:

typescript
/**
 * 繁體中文說明
 * English description
 */

/**
 * 繁體中文說明 / English description
 */

Incorrect patterns to avoid:

typescript
// ❌ Using inline comments (NOT allowed - must use block comments)
const value = 1; // 這是錯的

// ❌ English only (fake bilingual)
/**
 * Process data
 * Process data
 */

// ❌ Two English lines (no Chinese)
/**
 * English description
 * English description
 */

// ❌ English first, Chinese second (wrong order)
/**
 * English description / 繁體中文說明
 */

// ❌ English only (fake bilingual)
// Process data
// Process data

Correct patterns:

typescript
// ✅ Single-line block comment
/** 繁體中文說明 / English description */

// ✅ Multi-line block comment
/**
 * 繁體中文說明
 * English description
 */

// ✅ All member comments use block comments
/** 當前工作目錄 / Current working directory */
const cwd = process.cwd();

Correct patterns:

typescript
// ✅ Single-line block comment
/** 處理資料 / Process data */

// ✅ Multi-line block comment
/**
 * 處理使用者輸入資料並進行驗證
 * Process and validate user input data
 */

// ✅ Single-line with detail
/** 處理使用者輸入資料並進行驗證 / Process and validate user input data */

Code Formatting Rules

The project-wide comment and formatting rules live in the repository rules. For guidance on comment placement, block vs inline preferences, and other project conventions, please refer to:

• rules/comment-format-rules.md

Examples

See references/examples.md for detailed before/after examples covering:

• Class and member comments (using block comments)
• Complex logic blocks (using block comments)
• Array element comments (using block comments)
• Preserving original block comment style
• Single-line vs multi-line block comments