🤔

AIのためにWhatをコメントに書くのもありかもしれない

2025/03/16に公開

 検証環境Cursor: v0.46.11
model: claude-3.5-sonnet

 プログラミングのベストプラクティスは変わっていく？コメントには「何をしているコードか（What）」ではなく「なぜそのコードを書いたか（Why）」を書くのが良いと言われることが多い。

コードが何をしているかは見ればわかるし、コメントで説明しないといけないようならそのコードは複雑すぎる可能性がある。

自分も普段はこの考えを原則としてコメントをつけていることが多い。
// BAD： 何をしているかを書く
async function runJob(): number {
    await runTask1();

    // タスク間にスリープを挟んでおく
    await sleep(1);

    await runTask2();
}

// GOOD： なぜそのコードを書いたのかを書く
async function runJob(): number {
    await runTask1();

    // スリープを挟み外部APIのレート制限を緩和する
    await sleep(1);

    await runTask2();
}
しかしCursorでコードを書いている最近は、この原則に固執せず、あえてWhatを書くのもいいのではないかと思えてきた。

例えば擬似コードだったり、プロンプト的に「こういうコードを書きたい」をコメントすることがある。
/**
 * Usernameとして有効か
 * 
 * 以下の条件を満たしていること
 * - 5文字以上
 * - 英数字と限られた記号のみを含む 
 * - 記号は_-~のみが使用可能
 * - 先頭の文字は英数字のみ使用可能
 */
function validateUsername(username: string): boolean {
    // ※ 以下はAIが書いてくれたコード

    // 5文字以上であることを確認
    if (username.length < 5) return false;

    // 先頭の文字が英数字であることを確認
    if (!/^[a-zA-Z0-9]/.test(username)) return false;

    // 全ての文字が英数字または許可された記号（_-~）のみであることを確認
    if (!/^[a-zA-Z0-9_\-~]+$/.test(username)) return false;

    return true;
}
こういったAIへの指示のためのコメントはまさに「What」でしかない。原則に従うとコード生成された後は消されることになる。

しかし残すことでメリットもありそうだと感じている。
例えば、仕様変更のときコメントをプロンプトとして使える。
コメントを書き換えて、
+ * - 記号は_-~$のみが使用可能
+ * - 先頭の文字は英字のみ使用可能
- * - 記号は_-~$のみが使用可能
- * - 先頭の文字は英字のみ使用可能
チャットすればコードを書き換えてくれる


また、コメントを土台にセルフレビューを行うこともできる。
仕様的なことを書いたコメントは歴史とともにコードとの乖離が大きくなっていくのが常だが、そこをAIで補完しやすくなったのも良いポイントだと思う。

 結局どうなの正直わからない。サンプルコードは「そんなの自分で書いたほうが早い」というコードなのでAIの能力がこの先どれだけ向上するか、良いプロンプトを書けるか次第
人間側がどれだけAIのお膳立てをするべきかも今後次第
本当はコメントを書くより、仕様の書かれたドキュメントをSSoTとして参照したい。CursorのDocs機能で社内ドキュメントを読めたら一番いいと思っている

検証環境

プログラミングのベストプラクティスは変わっていく？

結局どうなの

Discussion