Table of Contents
چرا خوانایی کد مهم است؟
وقتی تازه شروع میکنید، معمولاً فقط میخواهید «کد کار کند». اما خیلی زود متوجه میشوید:
- لازم است چند روز یا چند ماه بعد کد خودتان را دوباره بخوانید.
- میخواهید کد را با دوستتان یا در یک پروژهٔ تیمی به اشتراک بگذارید.
- میخواهید خطاها را راحتتر پیدا و رفع کنید.
کدی که «تمیز و خوانا» نوشته شده باشد:
- سریعتر فهمیده میشود.
- راحتتر تغییر داده میشود.
- کمتر دچار باگ و اشتباه میشود.
- میتواند بهعنوان نمونهکد خوب برای دیگران استفاده شود.
هدف این بخش این است که به شما عادتها و الگوهایی یاد بدهد که از همین ابتدای مسیر، کد شما را حرفهایتر و قابلفهمتر کند.
نامگذاری خوب
نام متغیرها و توابع
نامها مهمترین ابزار برای خوانایی هستند. کدی که نام خوب دارد، حتی بدون کامنت هم قابل فهم است.
اصول کلی
- معنادار باشد، نه مبهم:
- بد:
x,y,a1 - خوب:
age,user_name,total_price - انگلیسی ساده استفاده کنید (در دنیای برنامهنویسی استاندارد است).
- از کلمات کامل یا خیلی قابلفهم استفاده کنید:
- بد:
tp,usr,np - بهتر:
total_price,user,new_password - از نامهای خیلی طولانی و جملهای هم خودداری کنید:
- بد:
price_of_all_products_in_the_shopping_cart - بهتر:
cart_total
سبک نامگذاری در پایتون (PEP 8)
در پایتون برای متغیر و تابع معمولاً این سبک استفاده میشود:
- حروف کوچک + جدا کردن کلمات با
_: user_nameget_user_agecalculate_average
مثال بد و خوب:
# بد
a = 18
b = 21
c = (a + b) / 2
# خوب
age_ali = 18
age_sara = 21
average_age = (age_ali + age_sara) / 2فقط با نامها، معنی کد مشخصتر شد.
نامگذاری ثابتها
اگر مقدار ثابتی دارید که قرار نیست عوض شود (مثل PI، TAX_RATE)، از حروف بزرگ استفاده کنید:
PI = 3.14159
MAX_LOGIN_ATTEMPTS = 5ساختاردهی و فاصلهگذاری در کد
کد تمیز مثل یک متن منظم است: پاراگراف، فاصله، و خطهای خالی دارد تا چشم و مغز راحتتر آن را دنبال کنند.
تورفتگی (indentation) منظم
پایتون خودش شما را مجبور میکند از تورفتگی استفاده کنید، ولی مهم است که:
- همیشه از ۴ فاصله (space) برای هر سطح تورفتگی استفاده کنید.
- از ترکیب
tabوspaceخودداری کنید.
مثال:
# بد - تورفتگی نامنظم
if age>18:
print("Adult")
print("You can enter")
# خوب - تورفتگی منظم
if age > 18:
print("Adult")
print("You can enter")فاصلههای خالی (Whitespace)
فاصلهٔ درست، خوانایی را بالا میبرد.
- دور عملگرها فاصله بگذارید:
- بد:
total=price*count+tax - خوب:
total = price * count + tax - بعد از
,یک فاصله بگذارید: - بد:
numbers = [1,2,3,4] - خوب:
numbers = [1, 2, 3, 4] - اطراف
=در تعریف متغیر فاصله بگذارید: - بد:
age=20 - خوب:
age = 20
خطهای کوتاه
سعی کنید طول هر خط را خیلی زیاد نکنید (در استاندارد پایتون حدود ۷۹ کاراکتر پیشنهاد شده است). اگر خط طولانی شد، آن را بشکنید:
# خط طولانی (بد)
message = "Your total price is " + str(total_price) + " and your discount is " + str(discount) + " percent."
# شکستن به چند قسمت (بهتر)
message = (
"Your total price is " + str(total_price) +
" and your discount is " + str(discount) +
" percent."
)استفادهٔ درست از کامنتها
کامنتها در فصل قبلی معرفی شدهاند؛ اینجا روی «چطور درست استفاده کنیم» تمرکز میکنیم.
کامنت چهچیزی را باید توضیح دهد؟
- چرا کاری را انجام میدهید، نه فقط چه کاری انجام میدهید.
- منطق خاص، محدودیتها، یا نکتههای مهمی که از روی کد بهتنهایی واضح نیستند.
مثال:
# بد - تکرار واضح کد
x = x + 1 # add 1 to x
# بهتر - توضیح "چرا"
x = x + 1 # move to the next dayکامنتهای خوب و بد
- کامنتهای خوب:
- توضیح قوانین کسبوکار (Business rules)
- هشدار درباره رفتار خاص
- اشاره به باگهای شناختهشده (در پروژههای واقعی)
- کامنتهای بد:
- فقط تکرار کد
- قدیمی و بیارتباط (کد عوض شده، کامنت عوض نشده)
مثال:
# بد
price = price * 0.9 # multiply price by 0.9
# خوب
price = price * 0.9 # apply 10% discount for loyal customerکامنتهای بلوکی
برای توضیح یک بخش نسبتاً طولانی از کد، میتوانید بالای آن، یک «بلاک کامنت» بنویسید:
# محاسبهٔ نمرهٔ نهایی:
# - 40% میانترم
# - 60% پایانترم
# اگر نمره زیر 10 باشد، دانشجو مردود است.
final_score = midterm * 0.4 + final * 0.6سازماندهی کد و تکهتکه کردن آن
کد تمیز معمولاً از تکههای کوچکتر و هدفدار تشکیل شده است؛ نه یک تکهٔ بزرگ بیسر و ته.
پرهیز از «تابع یا بلوک غولپیکر»
اگر یک تابع یا بخشی از کد:
- خیلی طولانی شده،
- کارهای مختلفی انجام میدهد،
- فهمیدنش سخت شده،
زمان آن است که آن را به چند تابع کوچکتر تقسیم کنید.
مثال:
# نسخهٔ شلوغ و مبهم
def process_user():
name = input("Name: ")
age = int(input("Age: "))
# بررسی سن
if age < 18:
print("Too young")
return
# محاسبهٔ کد عضویت
code = name[:3].upper() + str(age)
print("Your code:", code)
# نسخهٔ تمیزتر
def get_user_info():
name = input("Name: ")
age = int(input("Age: "))
return name, age
def is_allowed_age(age):
return age >= 18
def generate_user_code(name, age):
return name[:3].upper() + str(age)
def process_user():
name, age = get_user_info()
if not is_allowed_age(age):
print("Too young")
return
code = generate_user_code(name, age)
print("Your code:", code)نسخهٔ دوم طولانیتر است، اما هر بخش آن هدف مشخص و نام قابلفهم دارد؛ در پروژههای واقعی معمولاً چنین کدی خیلی بهتر نگهداری میشود.
سبک کدنویسی (Coding Style) و PEP 8
پایتون یک «راهنمای سبک کدنویسی» رسمی دارد به نام PEP 8. هدفش این است که همه بهطور مشابه کد بنویسند تا فهمیدن کد دیگران راحتتر شود.
نکات مهم PEP 8 که برای شما در این مرحله کاربردی است:
- استفاده از
snake_caseبرای نام متغیر و تابع:user_name - فاصله دور عملگرها (
+,-,=, …) - طول معقول خطها
- استفاده از ۴ فاصله برای تورفتگی
- یک خط خالی بین توابع سطح بالا
مثال سبک منظم:
def get_full_name(first_name, last_name):
"""برگرداندن نام کامل کاربر."""
full_name = first_name + " " + last_name
return full_name
def greet_user(full_name):
"""چاپ پیام خوشآمدگویی."""
print("Hello,", full_name)
first = "Ali"
last = "Ahmadi"
name = get_full_name(first, last)
greet_user(name)
نکته: رشتهٔ سهگانه درون تابع ("""...""") را در بخش توابع بهعنوان «docstring» معرفی خواهید دید؛ اینجا فقط بهعنوان مثال سبک آمده است.
پرهیز از تکرار (DRY)
یک اصل معروف در برنامهنویسی این است: DRY = Don’t Repeat Yourself
یعنی: «خودت را تکرار نکن».
اگر میبینید قطعهکدی را چند بار کپی میکنید، یعنی احتمالاً باید آن را در یک تابع قرار بدهید و آن تابع را صدا بزنید.
مثال:
# تکرار زیاد (بد)
print("Welcome, Ali")
print("Your age is 20")
print("Welcome, Sara")
print("Your age is 22")
# بهتر - استفاده از تابع
def show_user_info(name, age):
print("Welcome,", name)
print("Your age is", age)
show_user_info("Ali", 20)
show_user_info("Sara", 22)مزایا:
- اگر بخواهید شکل پیام را عوض کنید، فقط در یک جا کد را تغییر میدهید.
- احتمال اشتباه و ناهماهنگی کمتر میشود.
مثال کامل: نسخهٔ شلوغ در برابر نسخهٔ تمیز
نسخهٔ کمتر خوانا
n = int(input("How many numbers? "))
l = []
for i in range(n):
x = int(input("num: "))
l.append(x)
s = 0
for i in range(len(l)):
s += l[i]
avg = s / len(l)
print("avg:", avg)مشکلها:
- نامهای مبهم:
n,l,s - منطق در یک جای فشرده
- نبود کامنت توضیحی (در برنامهٔ بزرگتر نیاز حس میشود)
نسخهٔ تمیزتر
def get_numbers_from_user(count):
"""دریافت تعدادی عدد از کاربر و بازگرداندن آنها بهصورت لیست."""
numbers = []
for _ in range(count):
value = int(input("Enter a number: "))
numbers.append(value)
return numbers
def calculate_average(numbers):
"""محاسبهٔ میانگین یک لیست از اعداد."""
total = 0
for number in numbers:
total += number
return total / len(numbers)
count = int(input("How many numbers? "))
user_numbers = get_numbers_from_user(count)
average = calculate_average(user_numbers)
print("Average:", average)تفاوتها:
- نامهای معنادار (
numbers,total,average) - تکهتکه شدن منطق در دو تابع با هدف مشخص
- امکان استفادهٔ مجدد از توابع در برنامههای دیگر
- آمادهٔ رشد و توسعهٔ بیشتر برنامه
عادتهای خوب برای نوشتن کد تمیز
در عمل، «کد تمیز» بیشتر از اینکه یک مهارت ناگهانی باشد، نتیجهٔ عادتهای کوچک و مداوم است:
- قبل از نوشتن کد، چند ثانیه فکر کنید:
- چه متغیرهایی لازم دارم؟
- هر بخش چه کاری انجام میدهد؟
- نامی انتخاب کنید که فردای خودتان هم آن را بفهمد.
- بعد از اینکه کد کار کرد، یک بار فقط برای تمیز کردن آن را مرور کنید:
- نامها را بهبود دهید.
- خطوط طولانی را کوتاه کنید.
- کدهای تکراری را به تابع تبدیل کنید.
- برنامههای دیگران را بخوانید:
- به سبک نامگذاری آنها دقت کنید.
- ببینید چطور کد را تکهتکه کردهاند.
- از ابزارهای خودکار کمک بگیرید (در فصل IDE معمولاً معرفی شدهاند):
- قالببندها (formatter) مثل
black - بررسیکنندههای سبک (linter)
تمرینهای پیشنهادی
برای جا افتادن مفاهیم این بخش، میتوانید تمرینهای زیر را انجام دهید:
- یکی از برنامههای قبلی خودتان (مثلاً از فصلهای ۵–۷) را بردارید و:
- نام متغیرها را معنادارتر کنید.
- فاصلهها و تورفتگی را مرتب کنید.
- در صورت نیاز، چند تابع کوچک بسازید.
- یک برنامهٔ کوتاه (۱۰–۲۰ خط) با عمدیبودن نامهای بد و سبک شلوغ بنویسید، سپس:
- سعی کنید آن را به «تمیزترین نسخهٔ ممکن» تبدیل کنید.
- یک کد از اینترنت (ساده و آموزشی) پیدا کنید و:
- سعی کنید توضیح دهید چرا کد آنها خواناست یا نیست.
- اگر لازم بود، نسخهٔ تمیزتر خودتان را بنویسید.
با تمرین مداوم، «نوشتن کد تمیز و خوانا» برای شما به یک عادت طبیعی تبدیل میشود و در هر حوزهای از پایتون که ادامه دهید (وب، علم داده، خودکارسازی، …) به شدت به کارتان خواهد آمد.