より明確なコードのために、関数の目的を自明にすべき理由

ルール
Make a 関数の 目的 自明であること。
Function 名前 は 明確に 伝える 何を その 機能
する 説明 要求 読者に 読者に 検討 実装を 実装を

サポート言語: 45+

はじめに

目的を明らかにしない関数名は、開発者に動作を理解するために実装全体を読ませることになります。例えば、「 process() または handle() 何でもできる可能性があり、その実際の目的を推測するのに精神的な労力を要します。明確で記述的な名前、例えば validateUserEmail() または calculateOrderTotal() 意図を即座に伝え、コードを自己文書化させます。

なぜ重要なのか

コードの保守性：不明瞭な関数名は理解を遅らせます。開発者はビジネスロジックに集中する代わりに、関数が何をするのかを理解するために実装を読むのに時間を費やします。これは、数か月後にコードに戻る場合や、新しいチームメンバーが加わる場合にさらに悪化します。

誤った使用法: 曖昧な関数名は誤用の可能性を高めます。という名前の関数は update() 検証、変換、永続化、または通知を行う可能性があり、その名前が動作を明示していないため、開発者が誤って使用する原因となります。明確な名前は、制約と副作用を文書化することで誤用を防ぎます。

コード例

❌ 非準拠：

function process(data) {
    const result = data.map(item => ({
        ...item,
        processed: true,
        timestamp: Date.now()
    }));
    db.save(result);
    notifyService.send(result);
    return result;
}

誤っている理由： 名前 process() データに何が起こるかについては何も明らかになりません。読者は、アイテムの変換、データベースへの保存、通知の送信といった処理を理解するために、実装を調べる必要があります。関数の副作用と責任は隠蔽されています。

✅ 準拠済み:

function markItemsAsProcessedAndSave(data) {
    const processedItems = data.map(item => ({
        ...item,
        processed: true,
        timestamp: Date.now()
    }));
    db.save(processedItems);
    notifyService.send(processedItems);
    return processedItems;
}

これが重要な理由：この名前は、関数が項目を処理済みとしてマークし、保存することを明示的に示しています。読者は実装を読むことなく、関数の主な目的をすぐに理解できます。この名前は、副作用（データベースへの保存）を示唆し、適切な期待を設定します。

まとめ

関数名は、コードの検査を必要とせずに「何をするのか？」に答えるべきです。アクションを説明する動詞とターゲットを説明する名詞を含めてください。名前が長すぎる場合、その関数は多くのことをしすぎている可能性があり、分割する必要があります。