remove-ai-comments

「AI 風味」のコメントを削除する

目的

このスキルでは、AI コーディングアシスタントが生成することの多い、価値の低いコメントを削除する方法を説明します。こうしたコメントは、コードの構造を説明したり、自明なことを述べたり、冗長な「チュートリアル形式」の説明を加えたりして、プロフェッショナルなコードベースを煩雑にしがちです。

識別ガイド

次のカテゴリに該当するコメントを見つけて削除します。

1. 「ナレーター」

標準的なコーディング構文の開始を告げるコメントです。

• 削除する: // Begin function
• 削除する: // Loop through the array
• 削除する: // Define variables
• 削除する: // Initialize class
• 削除する: // End of if statement

2. 「翻訳者」

コードの行を英語で言い換えているだけで、補足情報を加えていないコメントです。

• 削除する: i += 1 // Increment i
• 削除する: return result // Return the result
• 削除する: print(error) // Print the error

3. 「ステップごとの説明」（AI チュートリアル形式）

標準的な処理の流れを説明する、番号付きの手順です。

• 削除する: // Step 1: Get the data
• 削除する: // Step 2: Validation
• 削除する: // Step 3: Return response

4. 「プレースホルダー」

テンプレートに残された、空または内容のないコメントです。

• 削除する: // TODO: implementation（実装がすでに完了している場合のみ）
• 削除する: /* Your code here */

保持ルール（削除しない場合）

次のコメントは削除しないでください。

• Docstring／JSDoc: 入力、出力、公開インターフェースを説明する API ドキュメント。
• 「理由」を説明するコメント: 特定の回避策、最適化、ビジネスロジック上の判断など、なぜその判断をしたかを説明するコメント。
• 警告: WARNING、CAUTION、または副作用に関する注記。
• Todo: 対応可能な TODO や FIXME の項目（ユーザーから削除を明示的に依頼された場合を除く）。

ワークフロー

1. 分析: 対象ファイルを読み、その目的を把握します。
2. 評価: コメントを確認します。利用可能な場合は python scripts/comment_density.py <file> を実行し、初期のコメント密度を把握します。
3. 処理:
   • コメントを一つずつ確認します。
   • コメントが「識別ガイド」の削除対象に該当する場合は、削除します。
   • 複雑なロジックを説明するコメントは、そのまま残すか、冗長すぎる場合は簡潔に修正します。
4. クリーンアップ: 結果として生じた連続する空行や末尾の空白を削除します。

例

変更前（AI 形式）:

# Import the datetime library
import datetime

# Function to get the current date
def get_date():
    # Step 1: Get today's date
    today = datetime.date.today()
    # Step 2: Return it
    return today

変更後（整理済み）:

import datetime

def get_date():
    return datetime.date.today()