コードの仕組みを繰り返すのではなく、意図を説明するコメントを記述する方法

ルール

コメント について 目標 目標 (理由)、 ではなく その 仕組み (方法)
コメント それ 単に 再述する 何を その コードが する 
提供する ない 追加 価値 提供しない できる 古くなる 時代遅れになる可能性があります。

サポート言語: 45+

はじめに

コードの動作を繰り返すだけのコメントは、追加の明確さを提供せず、実装と同期しなくなることがよくあります。コメントがコードと乖離すると、混乱を招き、レビューを遅らせます。有用なコメントは、意図、仮定、および決定の根拠を説明します。これにより、複雑なロジックの理解と保守が容易になります。

なぜ重要なのか

セキュリティ上の影響: 意図に基づいたコメントは、実装では見えない可能性のある検証、入力の信頼、またはアクセス制御に関する前提を露呈させます。

パフォーマンスへの影響: パフォーマンス関連の決定を明確にするコメントは、意図しない最適化や、期待されるパフォーマンス特性を損なう変更を回避するのに役立ちます。

コードの保守性：意図に焦点を当てたコメントは、開発者がコードの存在理由を理解するのに役立ち、その変更や監査に必要な時間を削減します。

攻撃対象領域: 明確なコメントは、内部関数を誤用して安全でない動作を引き起こしたり、攻撃対象領域を拡大したりする可能性を低減します。

コード例

❌ 非準拠：

// Loop through users
for (const user of users) {
    // Convert email to lowercase
    user.email = user.email.toLowerCase();
}

なぜこれが間違っているのか：これらのコメントは、コードが既に示している内容を繰り返しており、意図や制約に関するコンテキストを提供していません。

✅ 準拠済み:

/**
 * Normalize user emails so downstream permission checks
 * compare consistent lowercase values. Required because
 * external systems may send mixed-case emails.
 */
for (const user of users) {
    user.email = user.email.toLowerCase();
}

これが重要な理由：このコメントは、正規化がなぜ必要なのかを説明し、意図を明確にし、誤ったリファクタリングを防ぎます。

まとめ

各行が示す内容ではなく、コードが必要な理由を説明するコメントを記述してください。実装から明らかでない場合は、前提条件、制約、および根拠を記述します。これにより、コードが進化しても有用であり続ける、保守可能なドキュメントが作成されます。