ルール

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

サポート言語: 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();
}

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

結論

コードの各行が示す内容ではなく、そのコードが必要な理由を説明するコメントを記述してください。実装から明らかでない前提条件、制約、および推論については記述してください。これにより、コードが進化しても有用性を保つ保守性の高いドキュメントが作成されます。