自己文書化コードを書くために、記述的な変数名を使用すべき理由

ルール
記述的な 変数名を 使用します。
非常に短い 変数名は コードを 不明瞭にします。

サポート言語: 45+

はじめに

一文字または判読しにくい変数名は、コードを一目で理解する代わりに、読者が文脈から意味を推測することを強います。という名前の変数 d 日付、期間、距離、またはデータを表す可能性があり、関数全体でその目的を追跡するのに精神的な労力を要します。記述的な名前、例えば userCreatedDate または requestDuration 認知負荷なしに意図を即座に明確にする。

なぜ重要なのか

コードの保守性：不明瞭な変数名は理解を遅らせます。開発者は実際のロジックに集中する代わりに、x、tmp、valが何を表すのかを解明するのに時間を費やします。不適切な命名は、新しいロジックがどこに適合すべきか、既存の値が互いにどのように関連しているかが不明確であるため、コードの拡張も困難にします。さらに、曖昧な名前は、tmpやvalを検索しても意味のある結果が得られないため、コードベースを検索不能にします。これは、数か月後にコードに戻る場合や、新しいチームメンバーが加わる場合にさらに悪化します。

バグの導入: 曖昧な名前は、誤った変数を使用する可能性を高めます。複数の変数が類似した判読しにくい名前（d1, d2, d3）と、開発者は間違ったものを使用する可能性があり、名前が意味的な手がかりを提供しないため、コードレビューを通過してしまう微妙なバグを導入します。

コード例

❌ 非準拠：

function calcAmt(u, qty) {
    const p = u.prc;
    const d = u.disc || 0;
    const t = p * qty;
    const a = t - (t * d);
    const tx = a * 0.08;
    return a + tx;
}

なぜそれが不正確なのか： 変数名（例：） u, p, d, t, およびaは、その目的について何も明らかにしません。読者は、計算ロジックをたどって、それが何であるかを理解する必要があります p は価格で、 d は割引で、 t 小計です、そして a は税抜きの金額です。

✅ 準拠済み:

function calculateOrderAmount(product, quantity) {
    const price = product.price;
    const discount = product.discount || 0;
    const subtotal = price * quantity;
    const amountAfterDiscount = subtotal - (subtotal * discount);
    const tax = amountAfterDiscount * 0.08;
    return amountAfterDiscount + tax;
}

これが重要である理由： 各変数名はその内容を記述しています。 割引後の金額 計算状態を明確に示します。 税金 明確であり、 製品 そして 数量 本体を読む必要なく、関数の入力を明らかにします。

まとめ

コンテキストを必要とせずに意図を明らかにする名前を使用してください。簡潔さよりも明確さを優先してください。追加の文字は totalPrice 対 TP 実行にはコストがかかりませんが、理解にはかなりの時間を節約できます。