あなたのコードはなぜ読みにくい？改善するための5つのヒント

はじめに

「自分の書いたコードが他人に読みにくいと言われた…」そんな経験はありませんか？読みにくいコードは、バグを生みやすく、メンテナンス性を低下させる原因になります。この記事では、コードを読みやすく改善するための5つのヒントを紹介します。これらを意識することで、あなたのコードは他人にとっても自分にとっても理解しやすいものになるでしょう。

---

1. 意味のある変数名を使う

問題

読みにくいコードの典型例は、意味のない変数名を使っていることです。例えば、以下のようなコードでは何をしているかが直感的にわかりません。

x = 10
y = 20
z = x + y

改善方法

変数名にはその役割や意味がわかる名前を付けましょう。以下のように変更するだけで、コードが何をしているかが一目でわかります。

apple_price = 10
banana_price = 20
total_price = apple_price + banana_price

ヒント

• 一般的な略語（例: idx はインデックス）以外は避ける
• 長すぎず短すぎない名前を心がける

---

2. 適切なコメントを書く

問題

コメントが不足している、または不要なコメントが多いと、コードが読みにくくなります。

# xに10を代入する
x = 10

# yに20を代入する
y = 20

# xとyを足してzに代入する
z = x + y

このようなコメントは冗長であり、読む人にとって逆に負担になります。

改善方法

コメントは「なぜその処理を行うのか」を説明するために使います。「何をしているか」はコードそのものが伝えるべきです。

# 商品価格を合計するための計算
apple_price = 10
banana_price = 20
total_price = apple_price + banana_price

ヒント

• コメントを書く際は、「なぜこの処理が必要なのか」を意識する。
• 明らかな内容（例えば x += 1 # xに1を加える）はコメントしない。

---

3. コードのフォーマットを整える

問題

インデントが揃っていない、行間が詰まりすぎているなど、フォーマットが乱れているとコードが読みにくくなります。

def calculate_total_price(apple,banana):
    total=apple+banana;return total;

改善方法

PEP8（Python Enhancement Proposal 8）など、言語ごとのコーディングスタイルガイドラインに従いましょう。以下のようにフォーマットを整えるだけで視認性が大幅に向上します。

def calculate_total_price(apple, banana):
    total = apple + banana
    return total

ヒント

• 自動フォーマッタ（例: Pythonならblackやautopep8）を活用する
• 必要に応じて空行を入れ、論理的なブロックごとに分ける

---

4. 複雑なロジックは関数化する

問題

複雑な処理が1つの関数やスクリプト内に詰め込まれていると、理解しづらくなります。

apple_price = 10
banana_price = 20
tax_rate = 0.1

total_price = apple_price + banana_price + (apple_price + banana_price) * tax_rate

print(f"Total price with tax: {total_price}")

改善方法

複雑なロジックは関数化して分割しましょう。これにより再利用性も向上します。

def calculate_tax(price, tax_rate):
    return price * tax_rate

def calculate_total_price_with_tax(apple, banana, tax_rate):
    total = apple + banana
    tax = calculate_tax(total, tax_rate)
    return total + tax

apple_price = 10
banana_price = 20
tax_rate = 0.1

total_price_with_tax = calculate_total_price_with_tax(apple_price, banana_price, tax_rate)
print(f"Total price with tax: {total_price_with_tax}")

ヒント

• 関数名には処理内容がわかる名前を付ける
• 関数内の行数はできるだけ少なくする（目安として10〜20行以内）

---

5. 不要なコードや重複した処理を排除する

問題

不要なコードや重複した処理があると、コード全体が冗長になり読みづらくなります。

apple_price = 10 * (1 + 0.1)  # 税込み価格計算1回目
banana_price = 20 * (1 + 0.1) # 税込み価格計算2回目

total_price_with_tax = apple_price + banana_price

print(f"Total price with tax: {total_price_with_tax}")

改善方法

重複した処理は共通化し、一箇所で管理できるようにします。

def calculate_tax_included(price, tax_rate):
    return price * (1 + tax_rate)

tax_rate = 0.1

apple_price_with_tax = calculate_tax_included(10, tax_rate)
banana_price_with_tax = calculate_tax_included(20, tax_rate)

total_price_with_tax = apple_price_with_tax + banana_price_with_tax

print(f"Total price with tax: {total_price_with_tax}")

ヒント

• 重複した処理には関数化やループ処理を検討
• 不要になったコードは削除し、常に最新状態を保つ

---

おわりに

読みやすいコードを書くことは、自分自身だけでなく他の開発者への配慮でもあります。本記事で紹介した5つのヒント：

1. 意味のある変数名を使う
2. 適切なコメントを書く
3. コードのフォーマットを整える
4. 複雑なロジックは関数化する
5. 不要なコードや重複した処理を排除する

これらを意識することで、あなたのコードはより読みやすく、メンテナンスしやすいものになるでしょう。ぜひ実践してみてください！