【小技巧】寫出乾淨易讀的 Python 程式：命名規則與註解技巧

寫程式不只是讓機器能執行，更是給「人」看的。寫得清楚，未來你自己或團隊的成員才能快速理解、維護與擴充。這篇文章將分享幾個實用的小技巧，幫助你寫出更乾淨、易讀的 Python 程式！

一、命名規則：讓變數和函式一目了然

命名是程式可讀性的靈魂。遵循一致、語意清晰的命名方式，可以大大降低閱讀成本。

1.1 使用有意義的英文單字

# 不好
a = 10
b = 20
c = a + b

# 好
price = 10
tax = 20
total_cost = price + tax

1.2 遵循 PEP 8 命名慣例

1. 變數、函式 : 小寫 + 底線 -> total_price, get_user()
2. 類別名稱 : 大駝峰（PascalCase） -> OrderDetail, UserInfo
3. 常數 : 全大寫 + 底線 -> MAX_LENGTH, PI

二、註解技巧：寫給「未來的你」看的說明

註解不是越多越好，而是剛剛好就好。寫註解的目標，是幫助讀者理解程式邏輯，而不是重複說明程式碼本身。

2.1 不要註解「明顯」的事情

# 不建議：註解沒增加資訊
i = 0  # 設定 i 為 0

# 建議：說明用途
i = 0  # 計數器，用於統計有效筆數

2.2 使用區塊註解組織程式碼結構

# 載入資料
load_data()

# 預處理資料
clean_data()

# 訓練模型
train_model()

2.3 函式內用「docstring」寫用途說明

def calculate_tax(price, rate):
    """
    計算稅金金額

    :param price: 原價
    :param rate: 稅率
    :return: 稅金
    """
    return price * rate

三、進階技巧：讓程式更好維護

3.1 把「魔法數字」換成常數

# 不好：不知道 60 是什麼
if seconds > 60:
    print("超過 1 分鐘")

# 好：用有意義的常數
MAX_SECONDS = 60
if seconds > MAX_SECONDS:
    print("超過 1 分鐘")

3.2 拆分長函式，讓每段邏輯單一明確

def process_user(user_id):
    # 拆成數個小函式來維持清晰結構
    data = load_user_data(user_id)
    clean_data = preprocess_data(data)
    save_to_database(clean_data)

結語

乾淨的程式不只是為了讓別人看得懂，更是幫助未來的自己少踩雷。從命名、註解到整體結構，每一個小細節都能讓程式更專業、更有品質。

學會這些技巧，你就不只是「能寫程式」的工程師，而是能寫出「好程式」的開發者。🚀