KAHIBARO Bookshelves
Discord Login Register

18.2. نوشتن کد تمیز و خوانا

چرا خوانایی کد مهم است؟

وقتی تازه شروع می‌کنید، معمولاً فقط می‌خواهید «کد کار کند». اما خیلی زود متوجه می‌شوید:

  • لازم است چند روز یا چند ماه بعد کد خودتان را دوباره بخوانید.
  • می‌خواهید کد را با دوست‌تان یا در یک پروژهٔ تیمی به اشتراک بگذارید.
  • می‌خواهید خطاها را راحت‌تر پیدا و رفع کنید.

کدی که «تمیز و خوانا» نوشته شده باشد:

  • سریع‌تر فهمیده می‌شود.
  • راحت‌تر تغییر داده می‌شود.
  • کمتر دچار باگ و اشتباه می‌شود.
  • می‌تواند به‌عنوان نمونه‌کد خوب برای دیگران استفاده شود.

هدف این بخش این است که به شما عادت‌ها و الگوهایی یاد بدهد که از همین ابتدای مسیر، کد شما را حرفه‌ای‌تر و قابل‌فهم‌تر کند.

نام‌گذاری خوب

نام متغیرها و توابع

نام‌ها مهم‌ترین ابزار برای خوانایی هستند. کدی که نام خوب دارد، حتی بدون کامنت هم قابل فهم است.

اصول کلی

  • معنادار باشد، نه مبهم:
    • بد: 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_name
    • get_user_age
    • calculate_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)
  • تکه‌تکه شدن منطق در دو تابع با هدف مشخص
  • امکان استفادهٔ مجدد از توابع در برنامه‌های دیگر
  • آمادهٔ رشد و توسعهٔ بیشتر برنامه

عادت‌های خوب برای نوشتن کد تمیز

در عمل، «کد تمیز» بیشتر از اینکه یک مهارت ناگهانی باشد، نتیجهٔ عادت‌های کوچک و مداوم است:

  1. قبل از نوشتن کد، چند ثانیه فکر کنید:
    • چه متغیرهایی لازم دارم؟
    • هر بخش چه کاری انجام می‌دهد؟
  2. نامی انتخاب کنید که فردای خودتان هم آن را بفهمد.
  3. بعد از اینکه کد کار کرد، یک بار فقط برای تمیز کردن آن را مرور کنید:
    • نام‌ها را بهبود دهید.
    • خطوط طولانی را کوتاه کنید.
    • کدهای تکراری را به تابع تبدیل کنید.
  4. برنامه‌های دیگران را بخوانید:
    • به سبک نام‌گذاری آن‌ها دقت کنید.
    • ببینید چطور کد را تکه‌تکه کرده‌اند.
  5. از ابزارهای خودکار کمک بگیرید (در فصل IDE معمولاً معرفی شده‌اند):
    • قالب‌بندها (formatter) مثل black
    • بررسی‌کننده‌های سبک (linter)

تمرین‌های پیشنهادی

برای جا افتادن مفاهیم این بخش، می‌توانید تمرین‌های زیر را انجام دهید:

  1. یکی از برنامه‌های قبلی خودتان (مثلاً از فصل‌های ۵–۷) را بردارید و:
    • نام متغیرها را معنادارتر کنید.
    • فاصله‌ها و تورفتگی را مرتب کنید.
    • در صورت نیاز، چند تابع کوچک بسازید.
  2. یک برنامهٔ کوتاه (۱۰–۲۰ خط) با عمدی‌بودن نام‌های بد و سبک شلوغ بنویسید، سپس:
    • سعی کنید آن را به «تمیزترین نسخهٔ ممکن» تبدیل کنید.
  3. یک کد از اینترنت (ساده و آموزشی) پیدا کنید و:
    • سعی کنید توضیح دهید چرا کد آن‌ها خواناست یا نیست.
    • اگر لازم بود، نسخهٔ تمیزتر خودتان را بنویسید.

با تمرین مداوم، «نوشتن کد تمیز و خوانا» برای شما به یک عادت طبیعی تبدیل می‌شود و در هر حوزه‌ای از پایتون که ادامه دهید (وب، علم داده، خودکارسازی، …) به شدت به کارتان خواهد آمد.

Views: 0

Comments

Please login to add a comment.

Don't have an account? Register now!

Where to Move

Move chapter:

  • ☰ 1. فصل ۱: برنامه‌نویسی چیست؟
    • ☰ 1.1. برنامهٔ کامپیوتری چیست؟
      • ☰ 1.2. پایتون چیست؟
        • ☰ 1.3. پایتون کجا استفاده می‌شود؟
          • ☰ 1.4. چگونه برنامه‌نویسی به حل مسائل کمک می‌کند
            • ☰ 1.5. اولین برنامهٔ پایتون شما
            • ☰ 2. فصل ۲: راه‌اندازی پایتون
              • ☰ 2.1. نصب پایتون (ویندوز / macOS / لینوکس)
                • ☰ 2.2. استفاده از پایتون در ترمینال
                  • ☰ 2.3. استفاده از یک IDE (IDLE / VS Code)
                    • ☰ 2.4. اجرای اسکریپت‌های پایتون
                      • ☰ 2.5. حالت تعاملی پایتون
                      • ☰ 3. فصل ۳: متغیرها و انواع داده
                        • ☰ 3.1. متغیر چیست؟
                          • ☰ 3.2. ایجاد متغیرها
                            • ☰ 3.3. اعداد (`int`، `float`)
                              • ☰ 3.4. متن (`str`)
                                • ☰ 3.5. مقادیر بولی (`True`، `False`)
                                  • ☰ 3.6. بررسی نوع داده با `type()`
                                  • ☰ 4. فصل ۴: عملیات پایه
                                    • ☰ 4.1. عملیات حسابی
                                      • ☰ 4.2. کار با اعداد
                                        • ☰ 4.3. عملیات روی رشته‌ها
                                          • ☰ 4.4. ترکیب متن و متغیرها
                                            • ☰ 4.5. کامنت‌ها در پایتون
                                            • ☰ 5. فصل ۵: ورودی و خروجی کاربر
                                              • ☰ 5.1. دریافت ورودی از کاربر
                                                • ☰ 5.2. تبدیل ورودی به عدد
                                                  • ☰ 5.3. قالب‌بندی خروجی
                                                    • ☰ 5.4. نوشتن برنامه‌های تعاملی
                                                    • ☰ 6. فصل ۶: شرط‌ها (if / else)
                                                      • ☰ 6.1. عملگرهای مقایسه‌ای
                                                        • ☰ 6.2. عملگرهای منطقی
                                                          • ☰ 6.3. if، elif، else
                                                            • ☰ 6.4. شرط‌های تو در تو
                                                              • ☰ 6.5. اشتباهات رایج مبتدیان
                                                              • ☰ 7. فصل ۷: حلقه‌ها
                                                                • ☰ 7.1. چرا حلقه‌ها مفید هستند؟
                                                                  • ☰ 7.2. حلقه‌های while
                                                                    • ☰ 7.3. حلقه‌های for
                                                                      • ☰ 7.4. شمارنده‌های حلقه
                                                                        • ☰ 7.5. break و continue
                                                                          • ☰ 7.6. تمرین‌های حلقه
                                                                          • ☰ 8. فصل ۸: مجموعه‌های داده
                                                                            • ☰ 8.1. لیست‌ها (Lists)
                                                                              • ☰ 8.2. تاپل‌ها (Tuples)
                                                                                • ☰ 8.3. دیکشنری‌ها (Dictionaries)
                                                                                  • ☰ 8.4. مجموعه‌ها (Sets – مقدماتی)
                                                                                    • ☰ 8.5. انتخاب ساختار دادهٔ مناسب
                                                                                    • ☰ 9. فصل ۹: توابع
                                                                                      • ☰ 9.1. چرا توابع مهم هستند؟
                                                                                        • ☰ 9.2. تعریف توابع
                                                                                          • ☰ 9.3. پارامترها و آرگومان‌ها
                                                                                            • ☰ 9.4. مقادیر بازگشتی
                                                                                              • ☰ 9.5. محدودهٔ متغیرها (محلی در برابر سراسری)
                                                                                                • ☰ 9.6. استفادهٔ مجدد از کد
                                                                                                • ☰ 10. فصل ۱۰: کار با فایل‌ها
                                                                                                  • ☰ 10.1. فایل چیست؟
                                                                                                    • ☰ 10.2. خواندن فایل‌های متنی
                                                                                                      • ☰ 10.3. نوشتن و افزودن به فایل‌ها
                                                                                                        • ☰ 10.4. مسیر فایل‌ها
                                                                                                          • ☰ 10.5. برنامه‌های ساده مبتنی بر فایل
                                                                                                          • ☰ 11. فصل ۱۱: خطاها و اشکال‌زدایی
                                                                                                            • ☰ 11.1. انواع خطاها
                                                                                                              • ☰ 11.2. خواندن پیام‌های خطا
                                                                                                                • ☰ 11.3. خطاهای رایج مبتدیان
                                                                                                                  • ☰ 11.4. try و except
                                                                                                                    • ☰ 11.5. راهبردهای اشکال‌زدایی
                                                                                                                    • ☰ 12. فصل ۱۲: استفاده از کتابخانه‌های پایتون
                                                                                                                      • ☰ 12.1. کتابخانه چیست؟
                                                                                                                        • ☰ 12.2. وارد کردن ماژول‌ها
                                                                                                                          • ☰ 12.3. کتابخانه‌های استاندارد
                                                                                                                            • ☰ 12.3.1. math
                                                                                                                              • ☰ 12.3.2. random
                                                                                                                                • ☰ 12.3.3. datetime
                                                                                                                                • ☰ 12.4. نصب کتابخانه‌های خارجی با pip
                                                                                                                                • ☰ 13. فصل ۱۳: برنامه‌نویسی شی‌گرا (OOP)
                                                                                                                                  • ☰ 13.1. برنامه‌نویسی شی‌گرا چیست؟
                                                                                                                                    • ☰ 13.2. کلاس‌ها و اشیاء
                                                                                                                                      • ☰ 13.3. ویژگی‌ها و متدها
                                                                                                                                        • ☰ 13.4. متد `__init__`
                                                                                                                                          • ☰ 13.5. کپسوله‌سازی
                                                                                                                                            • ☰ 13.6. وراثت (مقدماتی)
                                                                                                                                              • ☰ 13.7. مثال‌های سادهٔ شی‌گرا
                                                                                                                                              • ☰ 14. فصل ۱۴: خودکارسازی با پایتون
                                                                                                                                                • ☰ 14.1. خودکارسازی چیست؟
                                                                                                                                                  • ☰ 14.2. خودکار کردن وظایف ساده
                                                                                                                                                    • ☰ 14.3. کار با فایل‌ها و پوشه‌ها
                                                                                                                                                      • ☰ 14.4. خودکارسازی پردازش متن
                                                                                                                                                        • ☰ 14.5. زمان‌بندی اجرای اسکریپت‌ها
                                                                                                                                                          • ☰ 14.6. مثال‌های کاربردی خودکارسازی
                                                                                                                                                          • ☰ 15. فصل ۱۵: توسعهٔ وب با پایتون
                                                                                                                                                            • ☰ 15.1. وب چگونه کار می‌کند؟ (نمای کلی)
                                                                                                                                                              • ☰ 15.2. آشنایی با Flask
                                                                                                                                                                • ☰ 15.3. ساخت یک وب‌سرور ساده
                                                                                                                                                                  • ☰ 15.4. مسیرها و قالب‌ها (Templates)
                                                                                                                                                                    • ☰ 15.5. پردازش ورودی کاربر (فرم‌ها)
                                                                                                                                                                      • ☰ 15.6. API های بسیار ساده
                                                                                                                                                                      • ☰ 16. فصل ۱۶: علم داده با پایتون
                                                                                                                                                                        • ☰ 16.1. علم داده چیست؟
                                                                                                                                                                          • ☰ 16.2. کار با داده‌ها
                                                                                                                                                                            • ☰ 16.3. آشنایی با NumPy
                                                                                                                                                                              • ☰ 16.4. آشنایی با pandas
                                                                                                                                                                                • ☰ 16.5. مصورسازی داده با matplotlib
                                                                                                                                                                                  • ☰ 16.6. مثال‌های سادهٔ تحلیل داده
                                                                                                                                                                                  • ☰ 17. فصل ۱۷: پروژه‌های کوچک
                                                                                                                                                                                    • ☰ 17.1. بازی حدس عدد
                                                                                                                                                                                      • ☰ 17.2. ماشین‌حساب ساده
                                                                                                                                                                                        • ☰ 17.3. فهرست کارها (To-Do List)
                                                                                                                                                                                          • ☰ 17.4. تولیدکنندهٔ رمز عبور
                                                                                                                                                                                            • ☰ 17.5. برنامهٔ آزمون (Quiz)
                                                                                                                                                                                              • ☰ 17.6. پروژهٔ کوچک وب یا داده
                                                                                                                                                                                              • ☰ 18. فصل ۱۸: گام‌های بعدی
                                                                                                                                                                                                • ☰ 18.1. چگونه پایتون را تمرین کنیم
                                                                                                                                                                                                  • ☰ 18.2. نوشتن کد تمیز و خوانا
                                                                                                                                                                                                    • ☰ 18.3. انتخاب یک حوزهٔ تخصصی
                                                                                                                                                                                                      • ☰ 18.3.1. توسعهٔ وب
                                                                                                                                                                                                        • ☰ 18.3.2. علم داده
                                                                                                                                                                                                          • ☰ 18.3.3. خودکارسازی
                                                                                                                                                                                                            • ☰ 18.3.4. توسعهٔ نرم‌افزار
                                                                                                                                                                                                            • ☰ 18.4. منابع یادگیری و انجمن‌ها
                                                                                                                                                                                                            • ☰ 19. پیوست
                                                                                                                                                                                                              • ☰ 19.1. برگهٔ تقلب دستور زبان پایتون
                                                                                                                                                                                                                • ☰ 19.2. خطاهای رایج و راه‌حل‌ها
                                                                                                                                                                                                                  • ☰ 19.3. واژه‌نامهٔ اصطلاحات