code-comments

コードコメント

コードを煩雑にせず、意図を説明する効果的なコメントを書くためのガイドラインです。

使用する場面

• 一見して分かりにくいコードを説明するコメントを追加するとき
• 既存のコメントが明確で正確かどうかを確認するとき
• コメントが必要か、コードをリファクタリングすべきかを判断するとき

対象外: 言語固有のドキュメント構文（JSDoc、docstring、Go の doc コメント）、ドキュメント生成、コミットメッセージ。

手順

1. コメントが必要か判断する — 可能な限り、コード自体で意図を明確にする必要があります。次の場合はコメントを付けるのが妥当です。

   • コードを見ただけでは 理由 が明らかでない
   • 一見して分かりにくい判断や制約がある
   • エッジケースや回避策の説明が必要である
   • 今後の作業や既知の制限事項を示す必要がある（TODO/FIXME）

2. 簡潔で正確なコメントを書く — すべての言葉に意味を持たせます。

   • 1 行のコメントを優先し、既存の規約やリンティングルールに従います
   • 1 つのコメントブロックは最大 3 行にします
   • コードの動作ではなく、意図や制約を記述します
   • 読み返さなくても意味が通じる、完結した考えを記述します

3. コメントを適切な位置に置く — 位置が重要です。

   • 説明するコードの上にコメントを置きます。特定の行を説明する場合を除き、行内には置きません
   • コメントは説明対象のコードの近くに置きます
   • コードが大きく右に押し出される末尾コメントは避けます

4. コメントを最新の状態に保つ — 古くなったコメントは、コメントがないよりも有害です。

   • コードの変更時にコメントも更新します
   • 該当しなくなったコメントは削除します
   • コメントアウトしたコードを説明なしで残さないでください

コメントすべきこと

• 動作ではなく理由: 仕組みではなく、その理由を説明します
• 一見して分かりにくい判断: 回避策、パフォーマンス上の選択、互換性の制約
• エッジケース: 境界条件、エラー処理の根拠
• TODO/FIXME: コンテキストを添えた既知の制限事項や今後の作業

コメントすべきでないこと

• 明白なコード: counter++ の上に置く // increment counter
• コメントアウトしたコード: 削除してください。Git の履歴に残ります
• 冗長な説明: コードから明らかな動作を繰り返し説明しないでください
• ノイズ: 区切り線、装飾的なコメント、作成者タグ（git blame を使ってください）

注意点

• コメントの付けすぎ: コードを言い換えるコメントは、価値を加えずノイズになります。コードの動作を説明する必要がある場合は、リファクタリングを検討してください。
• 古くなったコメント: コードと一致しないコメントは、後から読む人を誤解させます。コードを変更したら、必ずコメントを更新するか削除してください。
• コメントアウトしたコード: コメント内の不要なコードはファイルを煩雑にします。履歴はバージョン管理に残るので、そちらに任せてください。
• 曖昧なコメント: コンテキストのない「TODO: これを修正」は役に立ちません。何を、なぜ修正する必要があるのかを説明してください。
• 長いコメント: コメントが 3 行を超える場合は、コードのリファクタリングが必要か、説明をドキュメントに記載すべき可能性があります。

確認

コメントを追加または確認した後、次の点を確認してください。

• 各コメントが 動作ではなく理由 を説明している
• コメントが簡潔である（1 行を推奨、最大 3 行）
• 正当な理由のないコメントアウト済みコードが残っていない
• コメントが現在のコードの動作と一致している
• 明白なコードに冗長なコメントが付いていない

簡易チェックリスト：

Does this comment explain why, not what?
Is it as short as possible without losing accuracy?
Does it fit in one line (or three at most)?
Is the comment still accurate?
Could the code be clearer instead of needing this comment?