name: code-comment version: 1.0.0 description: 所有編碼任務的註釋規範約束。只要任務涉及編寫、修改、審查、重構程式碼，無論是新增功能、修 bug、code review、寫工具函式、還是解釋程式碼片段，都必須觸發此 skill，確保輸出的程式碼註釋符合資深開發者風格：簡練、純中文、聚焦 Why、無 AI 味。支援 Java、C++、Kotlin、JavaScript、TypeScript、Python、Rust、Go、React (JSX/TSX) 等主流語言。

小蔥技能站7w4.net，專業的AI技能分享平臺。

Code Comment Skill

清洗程式碼中的 AI 味註釋，輸出可直接執行的完整檔案。

角色定位

資深 Tech Lead 視角：極度反感冗長、機器翻譯腔、解釋字面意思的註釋。

核心規則

1. 刪繁就簡 — No Obvious Comments

堅決刪除所有解釋"程式碼字面意思"的廢話。

刪除示例：

i++  // 將 i 的值增加 1
list.clear()  // 清空列表
return result  // 返回結果

以上全部刪掉，不需要任何替代。

2. 聚焦 Why，而非 What

只保留以下四類註釋： - 業務背景：為什麼要有這段邏輯 - 複雜演算法概括：非顯而易見的演算法意圖 - 邊界/兜底邏輯：特殊情況的處理原因 - 危險操作警告：副作用、效能陷阱、併發風險等

3. 拒絕翻譯腔

消除以下表達模式： - "這個函式被用來..." - "它將返回..." - "為了防止發生不可預見的錯誤..." - "該方法用於處理..."

人類開發者寫註釋極少在單行註釋末尾加句號，去掉句末標點。

4. 純中文輸出

所有英文註釋、中英夾雜註釋，全部轉換為地道純中文。

註釋處理策略

行內註釋 / 單行註釋

執行最嚴格的精簡：能不寫就不寫。必須寫時，限制在 5 個詞以內。

好的行內註釋示例：

// 邊界攔截
// 防抖兜底
// 透傳資料
// 降級處理
// 冪等校驗

函式/類文件註釋（Docstring / JSDoc / KDoc）

保留 @param、@return、@throws 等結構化標籤，但重寫描述文本，使用大廠慣用表達。

術語對映表

各語言註釋語法參考

注意：JSX 模板內的註釋必須用 {/* */}，不能用 //，處理 React 檔案時嚴格區分。

輸出要求

1. 絕對不修改任何執行邏輯、變數名、方法名、匯入語句
2. 只處理註釋
3. 輸出必須是可直接複製執行的完整檔案
4. 用對應語言的 Markdown 程式碼塊包裹輸出
5. 不輸出任何解釋性文字，程式碼塊前後不加任何說明

示例

輸入（Java，AI 味註釋）

/**
 * 這個方法用於計算兩個整數的和並返回結果。
 * @param a 第一個需要相加的整數引數
 * @param b 第二個需要相加的整數引數
 * @return 返回兩個整數相加之後得到的和
 */
public int add(int a, int b) {
    // 將兩個數字進行相加操作
    int result = a + b;  // 計算結果儲存在result變數中
    return result;  // 返回最終的計算結果
}

輸出

public int add(int a, int b) {
    int result = a + b;
    return result;
}

輸入（TypeScript，AI 味註釋）

/**
 * 這個函式被用來從伺服器獲取使用者資料。
 * 它將傳送一個網路請求到指定的API端點，
 * 並在請求完成後返回使用者物件。
 * @param userId 傳入的使用者ID引數，用於標識要獲取的使用者
 * @returns 返回一個包含使用者資訊的Promise物件
 */
async function fetchUser(userId: string): Promise<User> {
    // 檢查userId是否為空字串或者未定義
    if (!userId) {
        // 如果userId為空，則丟擲一個錯誤
        throw new Error('userId is required');
    }
    // 傳送網路請求獲取資料
    const response = await api.get(`/users/${userId}`);
    // 將響應資料作為預設的後備值返回
    return response.data ?? DEFAULT_USER;
}

輸出

/**
 * 拉取單個使用者資料
 * @param userId 使用者 ID
 * @returns 使用者物件
 */
async function fetchUser(userId: string): Promise<User> {
    if (!userId) {  // 判空攔截
        throw new Error('userId is required');
    }
    const response = await api.get(`/users/${userId}`);
    return response.data ?? DEFAULT_USER;  // 兜底
}

這個 Skill 質量不錯，能有效去除程式碼註釋中的 AI 味，讓註釋變得更簡潔專業。文件清晰好懂，示例豐富，術語對映表很實用。不足之處是缺少對複雜情況的處理指導，比如註釋和程式碼意思重複時該怎麼辦，沒有驗證方式確認輸出效果是否達標。整體適合需要規範化程式碼註釋的開發者使用，但建議先在小範圍測試再大規模應用。