はじめに

コメント、書いていますか？

「コメントは大切」とわかっていても、実際に書くのは思っている以上に困難です。

「何をしているか」を説明するコメントは書きやすいのですが、すぐにコードと齟齬が生まれて嘘になってしまいます。一方で、本当に必要なのは「なぜそうしているか」を説明するコメント。しかし、これが一番書きづらいと思います。

さらに厄介なのが、自分で書いている時は「当然こう書くでしょ」と思っていても、数ヶ月後に読み返すと「なぜこんな書き方をしたんだろう？」と疑問だらけになることです。

つまり、読んでいて「なぜ？」と思う箇所を事前に察知して、そこにコメントを付けることが理想的なのですが、これを人間が完璧にやるのは現実的ではありません。

なら、AIにやってもらいましょう

そこで、「AIに『なぜ？』と疑問に思う箇所を自動で見つけてもらい、適切な説明コメントを提案してもらうVSCode拡張機能を作ろう」と考え、開発するに至りました。
そうして出来上がったのがWhyCommentです。

WhyComment

WhyCommentは「なぜ？」と思いそうなコードの箇所を自動検出し、コメントの提案をしてくれるVSCode拡張機能です。

主な特徴

選択範囲分析: 右クリックメニューから選択したコードだけを分析可能
自動分析: ファイル保存時に前回からの差分を取り、変更行をLLMで解析
一覧表示: サイドパネルに「行番号」「なぜ？」を表示
ワンクリック挿入: 提案コメントを右クリックすると、対象行の直前にコメントを追加
自動コメント推測: さらに自動でコメントの候補を3つ推測することも可能

実際の動作イメージ

このようなコードに対してWhyCommentを使ってみます。

function calculatePrice(items) {
    let total = 0;
    
    for (let item of items) {
        total += item.basePrice;
    }
    
    for (let item of items) {
        if (item.category === 'electronics') {
            total += item.basePrice * 0.08; 
        }
    }
    
    total *= 1.1;
    
    if (total > 10000) {
        total *= 0.95;
    }
    
    return Math.round(total);
}

すると、WhyCommentはこのコードを見て次のようにコメントするべき箇所を提案してくれます。

これに対してユーザーは3つのアクションを取れます。

Apply Suggestion: 提案を受け入れ、ユーザー自身がコメントを入力する
Ignore Suggestion: 提案を無視し、指摘を削除する
Suggest Comment Variants: LLMを利用して、適切なコメントを生成する

Suggest Comment Variantsでは、42行目（if (total > 10000)）に対してこのようなコメントを提案してくれます。

このように、「なぜその計算をしているのか」 をコメントとして残せるため、未来の自分やチームメイトが読みやすくなります。

利用方法

下記からインストールします。

Ctrl+,で設定画面を開き「WhyComment」で検索をして、OpenAIかClaudeのAPIキーを入力します。

Api Providerを入力したAPIキーに応じて変更します。

使うモデルなども設定画面から変更可能です。

デフォルトでAuto AnalyzeがONになっているので、APIキーを入力するだけでファイル保存時に自動でコメントが必要な個所が出てきたらEXPLORERタブのWHYCOMMENT欄に指摘されます。
手動でコードを範囲選択して、右クリックからWhyComment: Analyze Selectionをして解析することもできます。

さいごに

LLMプロバイダーやモデルによって出力が違いますが、ClaudeのHaiku 3.5がコスパが良いのでデフォルト値としています。

WhyCommentはまだ発展途上ですが、チーム開発や自分の学びを加速させるツールだと感じています。
気になった方はぜひインストールして試してみて、フィードバックをいただけると嬉しいです！