ルール 

関数 なし 説明 コメントなし。
関数 説明 コメント は 難しい 理解 
理解 ために 他の 開発者にとって

サポート言語: 45+

はじめに

コメントのない関数は、開発者が実装の詳細から意図を推測することを強いる。これによりコードレビューが遅延し、保守時のエラー発生率が高まる。説明の欠如は、検証条件や入力期待値、セキュリティ制約に関する前提条件も隠蔽する。明確なドキュメントは誤用を減らし、チームがコードの挙動を迅速に理解する助けとなる。

なぜそれが重要なのか

セキュリティ上の影響：コメントの欠如は、検証、認可チェック、信頼できる入力に関する前提条件を隠蔽し、悪用を容易にし、セキュリティリスクを高める。

パフォーマンスへの影響:文書化されていない関数が誤って使用される可能性があり、高コストな操作の繰り返し、不要な解析、または非効率的なデータ処理を引き起こす恐れがあります。

保守性：意図が文書化されていない場合、開発者はロジックの読み取りやリバースエンジニアリングに多くの時間を費やすため、リファクタリングやオンボーディングが遅延する。

コード例

非準拠：

// No explanation of expected input or security assumptions
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

誤りの理由：この関数はセキュリティに関連するフィールドを処理するが、信頼できるソース、期待される構造、入力制約に関する前提条件を文書化していない。

✅ 準拠：

/**
 * Normalize user data from external input.
 * Expects: `user` contains `id`, `email`, and `roles`.
 * Rejects invalid structures and filters unsafe role values.
 * Ensures normalized identifiers and lowercased email for consistency.
 */
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

これが重要な理由：コメントは意図、期待される入力、セキュリティ制約を文書化し、使用方法を予測可能にし、安全でない統合を防ぎます。

結論

シグネチャから意図、前提条件、制約が明らかでない関数には、明確なコメントを追加してください。関数が何を期待し、何を返し、セキュリティに関連する動作があるかを文書化します。これによりレビューの品質が向上し、誤用が減り、コードベース全体で予測可能な動作が保証されます。