コードコメントを書く
コードコメントは、コードだけでは読み取りにくい理由や制約を補うために使います。処理を一行ずつ英語にするより、なぜその処理が必要か、変更すると何に影響するかを残しましょう。以下のコメントは説明用の例です。
処理の言い換えより、理由を書く
// Keep the previous results visible to avoid flicker while loading.
日本語の意味: 読み込み中のちらつきを避けるため、前の結果を表示したままにします。
Keep the previous results visible to avoid flicker while loading.
読み込み中のちらつきを避けるため、前の結果を表示したままにします。
サイト共通の読み上げ設定
音声の選択肢を重視する場合は、Microsoft Edgeでの利用をおすすめします。2026年11月時点の確認環境では、他のブラウザーより選べる音声が比較的豊富でした。利用できる音声はOS・ブラウザーのバージョン・設定などによって異なります。
「試聴」で現在の速度と各音声を確認できます。試聴する英文：Hello! Let's practice English together.
全ページで共通です。変更は次の再生開始から適用され、連続再生中の設定は変わりません。このブラウザーに保存されます。
Increment the counterのようにコードから明らかな説明を毎回足す必要はありません。一方、意外な仕様や外部システムの制約は、根拠がわかるように補います。
// Do not retry this request: the legacy endpoint is not idempotent.
日本語の意味: 旧エンドポイントは冪等ではないため、このリクエストを再試行しないでください。
Do not retry this request: the legacy endpoint is not idempotent.
旧エンドポイントは冪等ではないため、このリクエストを再試行しないでください。
サイト共通の読み上げ設定
音声の選択肢を重視する場合は、Microsoft Edgeでの利用をおすすめします。2026年11月時点の確認環境では、他のブラウザーより選べる音声が比較的豊富でした。利用できる音声はOS・ブラウザーのバージョン・設定などによって異なります。
「試聴」で現在の速度と各音声を確認できます。試聴する英文：Hello! Let's practice English together.
全ページで共通です。変更は次の再生開始から適用され、連続再生中の設定は変わりません。このブラウザーに保存されます。
これは例の前提です。実際に確認した制約を書き、仕様や関連する記録への参照を添えます。Do not ...のような禁止形も、コードの変更に対する注意として適切な場合があります。
TODO：未完了の内容を具体化する
// TODO: Remove this compatibility branch after all clients use API v2.
日本語の意味: すべてのクライアントがAPI v2を使うようになった後、この互換性維持の分岐を削除します。
Remove this compatibility branch after all clients use API v2.
すべてのクライアントがAPI v2を使うようになった後、この互換性維持の分岐を削除します。
サイト共通の読み上げ設定
音声の選択肢を重視する場合は、Microsoft Edgeでの利用をおすすめします。2026年11月時点の確認環境では、他のブラウザーより選べる音声が比較的豊富でした。利用できる音声はOS・ブラウザーのバージョン・設定などによって異なります。
「試聴」で現在の速度と各音声を確認できます。試聴する英文：Hello! Let's practice English together.
全ページで共通です。変更は次の再生開始から適用され、連続再生中の設定は変わりません。このブラウザーに保存されます。
TODO: Fix laterだけでは、対象や完了条件がわかりません。必要なら管理先のissueや担当を添え、TODO・FIXMEの使い分けや書式はリポジトリの慣習に合わせます。コメントに書いたことだけで作業が担当者へ割り当てられるわけではありません。
関数の説明：契約を残す
以下はドキュメントコメントだけの例です。実際の実装と型に合う入力条件、戻り値、エラーを書きます。
/**
* Parses a positive integer from a decimal string.
* @param text - A string containing decimal digits only.
* @returns The parsed value as a safe integer.
* @throws RangeError if the value is zero or exceeds the safe integer range.
* @throws TypeError if the input contains non-digit characters.
*/
日本語の意味: 10進数字だけの文字列から正の整数を読み取ります。戻り値は安全な整数です。0または安全な整数の範囲を超える値にはRangeError、数字以外の文字を含む入力にはTypeErrorを送出する、という契約を示しています。
Parses a positive integer from a decimal string.
10進数の文字列から正の整数を読み取ります。
サイト共通の読み上げ設定
音声の選択肢を重視する場合は、Microsoft Edgeでの利用をおすすめします。2026年11月時点の確認環境では、他のブラウザーより選べる音声が比較的豊富でした。利用できる音声はOS・ブラウザーのバージョン・設定などによって異なります。
「試聴」で現在の速度と各音声を確認できます。試聴する英文：Hello! Let's practice English together.
全ページで共通です。変更は次の再生開始から適用され、連続再生中の設定は変わりません。このブラウザーに保存されます。
Parses ...と、冒頭の例にあるKeep ...では、文の形と伝えたいことが異なります。
Parses ...：関数が何をするかの説明
This function parses a positive integer from a decimal string.（この関数は10進数の文字列から正の整数を読み取ります）の主語を省略した形です。主語に当たるThis functionが三人称単数なので、現在形の動詞parseにsが付きます。Keep ...：実装・変更時に守ってほしい方針や注意
Keep the previous results visible ...（前の結果を表示したままにしてください）は、動詞の原形で始まる命令形です。この例では、保守担当者に「読み込み中も前の結果を表示する動作を維持する」という方針と、その理由を伝えています。
コードコメントの命令形は、必ずしも誰かへ今すぐ作業を依頼するものではありません。維持すべき動作や実装上の方針を示すためにも使います。
ただし、「関数の説明は必ずParses ...、注意は必ずKeep ...」という決まりではありません。関数の説明をParse ...のように命令形で書くスタイルもあります。何を伝えるコメントなのかを考え、周囲の文体やリポジトリの規約に合わせましょう。
更新時のチェック
実装を変えたら、コメントの前提や例外条件も更新します。型や名前だけで十分に伝わる情報を重複させず、古い説明が残らないようにします。
関連記事・参考資料
- PRの説明とレビュー
- README・手順書・技術記事
- Google Engineering Practices：What to look for in a code review：コメントやドキュメントもレビュー対象に含める考え方