2-1 省略しない・意図が伝わる名前

タイプ数を減らしたくて変数名を1〜2文字に省略すると、書いた本人ですら数週間後には各行が何の計算なのか思い出せなくなる。名前は省略せず、業務上の意味がそのまま読み取れる言葉を選ぶ。設計の第一歩は「実装中に何度も読み返される」ことを前提に名前を付けることだ。

顧問先への月次請求額の計算

✕ Bad

k1・k2・t・m が何の金額なのか、コードのどこにも手がかりがない

省略された名前

def calc(k1: int, k2: int, t: float, m: int) -> int:
    a = k1 + k2
    a = int(a * t)
    a = a - m
    if a < 0:
        a = 0
    return a

✓ Good

顧問料・記帳代行料・前受金と業務の言葉で命名すれば、各行の意図が仕様書なしで読める

意図が伝わる名前

TAX_RATE = 1.10

def calc_billing_amount(
    advisory_fee: int,        # 顧問料
    bookkeeping_fee: int,     # 記帳代行料
    advance_received: int,    # 前受金の充当額
) -> int:
    billing_amount = advisory_fee + bookkeeping_fee
    billing_amount = int(billing_amount * TAX_RATE)
    billing_amount = billing_amount - advance_received
    if billing_amount < 0:
        billing_amount = 0
    return billing_amount

名前を直しただけで「税込にして前受金を引いている」と読めるようになった。ただし billing_amount を計算途中で使い回している問題が残っている。これは次のトピックで解消する。

TAX_RATE = 1.10 def calc_billing_amount( advisory_fee: int, # 顧問料 bookkeeping_fee: int, # 記帳代行料 advance_received: int, # 前受金の充当額 ) -> int: billing_amount = advisory_fee + bookkeeping_fee billing_amount = int(billing_amount * TAX_RATE) billing_amount = billing_amount - advance_received if billing_amount < 0: billing_amount = 0 return billing_amount