A Python függvény akkor jó, ha első olvasásra világos. Ez az útmutató megmutatja, hogyan írható olvasható Python kód már kezdőként is.
Miért fontos az olvasható Python függvény
Sok kezdő megírja az első működő Python függvényét, majd pár hét múlva már nem érti, mit csinált. Az olvasható kód nem trükkökből épül. A lényeg az, hogy a függvény célja érthető legyen, a bemenetek világosak legyenek és a következő fejlesztő ne vakarja a fejét feleslegesen.
1. Nevezd el a Python függvény célját pontosan
A Python függvény neve legyen beszédes, mintha egy barátnak magyaráznád el, mit csinál. A jó név fél siker, mert csökkenti a kód olvasójának terhét.
Rossz példa:
def proc(d):
return sum(d) / len(d)Jó példa:
def calculate_average(numbers):
return sum(numbers) / len(numbers)A calculate_average név egyértelmű. A numbers paraméter világosan jelzi a bemenetet.
2. Használj leíró paraméterneveket a Python függvény írásakor
A paraméter neve legyen magyarázó. A kezdő betűk helyett használj érthető szavakat.
Rossz példa:
def discount(p, r):
return p * (1 - r)Jó példa:
def apply_discount(original_price, discount_rate):
return original_price * (1 - discount_rate)A függvény hívásakor azonnal látszik, mit jelentenek az értékek.
3. A Python függvény legyen rövid és egy feladatot végezzen
A túl sok feladat egy helyen átláthatatlan kódot eredményez. Jobb több kisebb függvény, mint egy nagy halmaz.
Rossz példa:
def process_order(items, customer_email, discount_code):
# Calculate total
subtotal = sum(item["price"] * item["quantity"] for item in items)
# Apply discount
if discount_code == "SAVE10":
discount = 0.10
elif discount_code == "SAVE20":
discount = 0.20
else:
discount = 0
total = subtotal * (1 - discount)
# Send email
subject = f"Order Confirmation"
body = f"Your order total is ${total:.2f}"
send_email(customer_email, subject, body)
return totalJó példa: a folyamat lépésekre bontása:
def calculate_order_subtotal(items):
return sum(item["price"] * item["quantity"] for item in items)
def get_discount_rate(discount_code):
discount_rates = {"SAVE10": 0.10, "SAVE20": 0.20}
return discount_rates.get(discount_code, 0)
def apply_discount_to_subtotal(subtotal, discount_rate):
return subtotal * (1 - discount_rate)
def send_order_confirmation_email(customer_email, total):
subject = "Order Confirmation"
body = f"Your order total is ${total:.2f}"
send_email(customer_email, subject, body)
def process_order(items, customer_email, discount_code):
subtotal = calculate_order_subtotal(items)
discount_rate = get_discount_rate(discount_code)
total = apply_discount_to_subtotal(subtotal, discount_rate)
send_order_confirmation_email(customer_email, total)
return totalA process_order így receptként olvasható.
4. Adj docstringet minden fontosabb Python függvény elejére
A név mutatja, mit csinál. A docstring megmutatja a célját, a bemeneteket és a visszatérési értéket.
Példa:
def calculate_shipping_cost(weight_kg, distance_km, is_express=False):
"""
Calculate shipping cost based on weight and distance.
Args:
weight_kg (float): weight in kilograms
distance_km (float): distance in kilometers
is_express (bool): express shipping option
Returns:
float: total cost
"""A docstring segít megérteni a működést kódolvasás nélkül is.
5. A Python függvény belsejében használj egyértelmű változókat
A kód akkor átlátható, ha a változók világosan jelzik a szerepüket.
Rossz példa:
def calc_bmi(w, h):
h_m = h / 100
res = w / (h_m**2)
return round(res, 1)Jó példa:
def calculate_bmi(weight_kg, height_cm):
height_meters = height_cm / 100
bmi = weight_kg / (height_meters**2)
return round(bmi, 1)A height_meters és bmi önmagáért beszél.
6. Kerüld a rejtélyes számokat és használj konstansokat
A mágikus számok félreértést okoznak. A konstansok egyértelművé teszik a szabályokat.
Rossz példa:
def calculate_late_fee(days_overdue):
if days_overdue <= 7:
return days_overdue * 2
else:
return 14 + (days_overdue - 7) * 5Jó példa:
def calculate_late_fee(days_overdue):
DAILY_FEE_FIRST_WEEK = 2
GRACE_PERIOD_DAYS = 7
BASE_FEE_AFTER_GRACE = 14
DAILY_FEE_AFTER_GRACE = 5
...A szabályok így láthatók és könnyen módosíthatók.
7. Adj típusjelölést minden Python függvény számára
A type hint megakadályozza a félreértést és megkönnyíti a fejlesztői hibakeresést.
Példa:
def format_user_greeting(user_name: str, age: int, is_member: bool = False) -> str:
membership_status = "member" if is_member else "guest"
return f"Hello {user_name}, age {age}. You are a {membership_status}."A típusok egy pillantásra érthetők.
Mit vigyél tovább ebből az útmutatóból
A Python függvény akkor valódi érték, ha az olvasó egy pillantással érti. A jól megválasztott név, a tiszta szerkezet, a dokumentált logika és az átgondolt változók együtt alakítják ki a kódot, amely működik és érthető. A digitális világ gyors fejlődése egyre több ilyen átlátható szabályt kívánna, különösen a szabályozási vitákban, ahol a pontosság a legfontosabb.
