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
3. Identify logic blocks - Find all logic blocks requiring comments (see Logic Block Requirements below)
4. Generate bilingual comments (Traditional Chinese zh-TW + English) - Apply format rules below
5. 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

// ❌ 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
}

// ❌ 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)

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

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

Correct Format (Using Block Comments)

// ✅ 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:

// ❌ 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。

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

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

// ❌ 錯誤：開頭 `/**` 與第一行文字同行，導致縮排混亂
/** 如果是 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 */

// ✅ 正確：開頭 `/**` 獨立一行，後續行正確對齊
/**
 * 如果是 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。

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

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

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

// ✅ 正確：使用單行區塊註解作為分隔線
/** ==================== 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:

/** 是否成功 / 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):

/**
 * 取得分組鍵的函式
 * 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。

/**
 * 繁體中文說明
 * 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:

/** 檢查使用者權限 / 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.

// ❌ 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:

/**
 * 逻辑说明一 / 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:

// ❌ 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;
}

// ✅ 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 / 錯誤示範（資訊冗餘）：

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

Correct Example / 正確範例：

/**
 * 從結果中取得舊版插件名稱
 * 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 / 錯誤（意思重複）：

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

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

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

/**
 * 此函數用於處理資料
 * 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:

/**
 * 工具函式集合
 * 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 characte

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->