コードの読みやすさを高めるテクニック: コメントの適切な使い方

コードの読みやすさを向上させるために、適切なコメントの使い方は非常に重要です。
本記事では、コメントを効果的に使用するためのテクニックについて解説します。

冗長なコメントは避ける

コードが既に明確に表現している内容をコメントで繰り返すことは避けましょう。
冗長なコメントは、コードを乱雑にし、メンテナンスの手間を増やします。

ただし、変数名が適切でない場合、コメントが必要になることもあります。

悪い例:

# 商品の価格を表す変数
p = 1000

良い例:

product_price = 1000

上記の悪い例では、pという変数名では、その変数が何を表しているのか明確ではありません。
そのため、コメントで説明を加えています。

しかし、このコメントは冗長です。

一方、良い例では、product_priceという変数名を使用することで、変数の意味が明確になります。
この場合、コメントは不要です。

適切な変数名を使用することで、コードの読みやすさが向上し、冗長なコメントを避けることができます。
変数名は、その変数が表す内容を正確に表現するようにしましょう。

名前付けの重要性については、次の記事で説明しています。

コードを読みやすくする努力を優先する

コメントを使ってコードの説明をするよりも、コード自体を読みやすくすることを優先しましょう。
適切な変数名や関数名を使用することで、コメントなしでもコードの意図が明確になります。

悪い例:

def calculate_price(data):
    # data[0]には商品の基本価格が含まれ、data[1]には税率が含まれる。
    # data[2]には割引率が含まれる。
    # 総価格を計算して返す。
    return data[0] + (data[0] * data[1]) - (data[0] * data[2])

良い例:

def calculate_price(data):
    base_price = get_base_price(data)
    tax = calculate_tax(data)
    discount = calculate_discount(data)
    return base_price + tax - discount

def get_base_price(data):
    return data[0]

def calculate_tax(data):
    base_price = get_base_price(data)
    tax_rate = data[1]
    return base_price * tax_rate

def calculate_discount(data):
    base_price = get_base_price(data)
    discount_rate = data[2]
    return base_price * discount_rate

悪い例では、calculate_price関数内でdata配列の要素に直接アクセスしており、コードの意図が分かりにくくなっています。
また、コメントで説明を加えていますが、コードを読みやすくする工夫が不足しています。

良い例では、get_base_price、calculate_tax、calculate_discount関数を別途定義することで、それぞれの処理を明確に分離しています。
これにより、calculate_price関数の意図が明確になり、コードの読みやすさが向上します。

また、関数名も処理の内容を的確に表現しているため、コメントがなくても関数の目的が理解しやすくなっています。
このように、コードを読みやすくする工夫を積極的に行うことで、コメントに頼らずともコードの意図を明確に伝えることができます。

コードが存在する理由を説明する

コードがなぜ存在するのか、その理由を説明するコメントは非常に有用です。
特に、ビジネス上の決定やバグ修正など、コード単体からは理解しにくい背景情報を提供することができます。

良い例1:

def calculate_shipping_fee(total_price):
    # 合計金額が5,000円以上の場合は送料無料
    # (キャンペーン期間: 2023年6月1日〜2023年8月31日)
    if total_price >= 5000 and datetime.now() < datetime(2023, 9, 1):
        return 0
    else:
        return 500

この例では、送料無料の条件が特定の期間に限定されていることをコメントで説明しています。
このようなビジネスロジックは、コードだけでは理解しにくいことがあるため、コメントを使って補足説明を加えることが有効です。

良い例2:

def calculate_bonus(employee):
    # 年末ボーナスの計算
    # 勤続年数が5年以上の社員には基本給の20%をボーナスとして支給
    # 勤続年数が10年以上の場合は基本給の30%を支給
    # ただし、2024年は特例として全社員に一律で基本給の25%を支給 (会社創立50周年記念)
    if datetime.now().year == 2024:
        return employee['salary'] * 0.25
    elif employee['years_of_service'] >= 10:
        return employee['salary'] * 0.3
    elif employee['years_of_service'] >= 5:
        return employee['salary'] * 0.2
    else:
        return 0

この例では、年末ボーナスの計算ロジックについて、コメントを使って詳細に説明しています。
特に、2024年の特例措置については、コード内の条件分岐だけでは理由が明確ではありません。

そこで、コメントを使って会社創立50周年記念であることを補足することで、コードの理解を助けています。
このように、コードが存在する理由や背景情報を説明するコメントは、コードの可読性を高め、メンテナンス性を向上させるために非常に有効です。

ただし、コメントは適切な位置に配置し、簡潔で明瞭な表現を心がけることが重要です。