「なぜ」を書くコメントの考え方が変わった話

この記事は一休.com Advent Calendar 2025 15日目の記事です。

はじめに

業務委託として一休で主にふるさと納税サイトの開発をしている星野です。
今回は、開発の中で「コメントとの向き合い方」が変わった経験についてまとめます。

特に、AI を活用したコーディングの中で日本語コメントの有効性に気づく場面があり、そこで得た発見を共有できればと思います。

元々のコメント観

「リーダブルコード」「達人プログラマ」などの書籍でもコメントの考え方が語られています。
自分が長く持っていたコメントに対する認識は次のようなものです。

• 「なにをしたか」ではなく「なぜそうしたのか」を書く
• コードに書いてあることをコメントに重ねない
• コメントに頼らず、コメントが少なくても読めるコードを書くのが理想

この考え方をベースに開発してきたのですが、バイブコーディングを試す中で少し見方が変わりました。

バイブコーディング中に書いた日本語のコメントでの気づき

AI に実装を任せてみたものの、複雑な条件判定の意図がうまく伝わらず苦戦していました。
そこで、自分の思考整理と AI の精度向上を兼ねて、日本語でコメントを書き始めたところ次のようになりました。
(コードはサンプルコードになります)

// canApplyDiscount は割引適用可否を返す
func canApplyDiscount(user *User, cart *Cart, campaign *Campaign) bool {
    // ログイン済みユーザーが対象
    isLoggedIn := user != nil && user.IsLoggedIn

    // カートに商品があり、最低金額以上なら対象
    isCartValid := !cart.IsEmpty() && cart.TotalAmount >= campaign.MinAmount

    // キャンペーン期間内なら対象
    isCampaignActive := campaign.IsActive(time.Now())

    // 初回購入限定でない、または初回購入者なら対象
    isEligibleForCampaign := !campaign.IsFirstPurchaseOnly || !user.HasPurchaseHistory()

    return isLoggedIn && isCartValid && isCampaignActive && isEligibleForCampaign
}

日本語のコメントを削除すると以下のようになります。

// canApplyDiscount は割引適用可否を返す
func canApplyDiscount(user *User, cart *Cart, campaign *Campaign) bool {
    isLoggedIn := user != nil && user.IsLoggedIn

    isCartValid := !cart.IsEmpty() && cart.TotalAmount >= campaign.MinAmount

    isCampaignActive := campaign.IsActive(time.Now())

    isEligibleForCampaign := !campaign.IsFirstPurchaseOnly || !user.HasPurchaseHistory()

    return isLoggedIn && isCartValid && isCampaignActive && isEligibleForCampaign
}

これを見比べたところ、「英語のコードだけよりも日本語コメントがある方が直感的に読めるな…」という当たり前の気づきがありました。

なぜ日本語コメントが読みやすいのか

自分の第一言語である日本語は、解釈のための余計な思考コストがありません。英語のコードやコメントは問題なく読めるものの、どうしても「翻訳」のステップが挟まります。
一方、日本語なら目に入った瞬間に意味を把握でき、全体の意図を素早くつかめます。特に処理の流れや条件分岐の意図など、「方向性」を理解したい場面では非常に有効だと感じました。

可読性のための日本語コメント

この気づき以降、複雑な流れや慣れない単語が登場する場面では、積極的に日本語で書き出すようになりました。

目的は以下の二つです。

• 初見の人や未来の自分が、コードの流れを直感的に追えるようにする
• 思考の抜け漏れや不自然な処理フローを早期に検知する

日本語を使うだけで、理解スピードが上がるのは想像以上でした。

ただし、使いどころには注意が必要

もちろん「すべてに日本語コメントを書くべき」という話ではありません。
基本スタンスはこれまで通り、

• なぜその実装なのかを書く
• コメントよりまずコードで表現する

ことが大切だと思っています。

特に注意したいのは、コメントが実装とずれてしまうケースです。
コメントと実装はどうしても二重記述になるため、実装だけが変更され、コメントが追従しないことがあります。
『良いコード/悪いコードで学ぶ設計入門』では、情報を正しく説明しなくなったコメントを「退化コメント」と呼んでいます。

実装の近くに書く

退化コメントを予防する対策として、僕はコメントと実装の「距離」をできるだけ近づけています。

// canApplyDiscount は割引適用可否を返す
func canApplyDiscount(user *User, cart *Cart, campaign *Campaign) bool {
    // ログイン済みユーザーが対象
    isLoggedIn := user != nil && user.IsLoggedIn

    // カートに商品があり、最低金額以上なら対象
    isCartValid := !cart.IsEmpty() && cart.TotalAmount >= campaign.MinAmount

    // キャンペーン期間内なら対象
    isCampaignActive := campaign.IsActive(time.Now())

    // 初回購入限定でない、または初回購入者なら対象
    isEligibleForCampaign := !campaign.IsFirstPurchaseOnly || !user.HasPurchaseHistory()

    return isLoggedIn && isCartValid && isCampaignActive && isEligibleForCampaign
}

実装の直前に置くことで「このコメントはこの処理に対応している」とすぐ理解できますし、意図と処理のズレにも気づきやすくなります。

完全な乖離防止は難しいものの、現実的で効果的なアプローチだと感じています。

まとめ

『リーダブルコード』には次のような言葉があります。

コードを理解するために役立つなら、何でも書こう（5章）

日本語コメントもまさにこの考え方に当てはまると思います。

• 迷いやすい箇所に
• 理解の手がかりになる形で
• 適切に使う
  これだけで可読性は一段上がり、未来の自分やチームの助けになります。

今後も、必要な場所に必要なだけコメントを残しながら、読みやすく保守しやすいコードを書いていきたいと思います。

参考文献

• リーダブルコード 5章 コメントすべきことを知る
• 良いコード/悪いコードで学ぶ設計入門 第11章 コメント
• 達人プログラマ 第2章 達人のアプローチ 二重化の過ち／第8章 達人のプロジェクト すべてはドキュメント
• プログラマが知るべき97のこと 16 コメントについてのコメント／17 コードにかけないことのみをコメントにする