۱۴۰۵ آبان ۲۶, سه‌شنبه
دلار آمریکا۲۶۷٬۷۰۵▼ ۰٫۳۷٪یورو۲۹۴٬۸۸۰▼ ۰٫۵۱٪درهم امارات۷۲٬۹۵۱▼ ۰٫۳۷٪سکه امامی۲۵۱٬۴۴۰٬۰۰۰▲ ۰٫۳۵٪طلای ۱۸ عیار (گرم)۲۴٬۶۴۷٬۷۰۰▲ ۰٫۳۳٪انس طلا۳٬۸۶۷ $▲ ۰٫۰۴٪تتر۲۶۹٬۶۳۷▲ ۰٫۰۹٪بیت‌کوین۶۴٬۹۰۵ $▼ ۰٫۴۶٪اتریوم۱٬۸۱۹ $▼ ۰٫۲۵٪سولانا۷۳٫۳۵ $▲ ۲٫۵۹٪اپل۳۵۲٫۷۸ $▼ ۰٫۹۸٪انویدیا۱۵۶٫۱۴ $▼ ۴٫۱۲٪مایکروسافت۵۱۷٫۹۹ $▼ ۱٫۱۲٪آلفابت (گوگل)۲۸۳٫۷۲ $▼ ۴٫۰۷٪تسلا۳۷۹٫۷۴ $▼ ۲٫۶۹٪شاخص نزدک۲۴٬۵۱۰ $▼ ۲٫۴۹٪
نرخ ارز

اصول کلین کد؛ راهنمای عملی نوشتن کد تمیز و قابل‌نگهداری

کلین کد یعنی کدی که دیگران راحت بخوانند و تغییر دهند؛ نام‌گذاری، توابع کوچک، مدیریت خطا، کامنت درست و بازآرایی را با مثال‌های پایتون یاد بگیرید.

کاور گرافیکی DevNA با عنوان «Clean Code»: اصول نوشتن کد تمیز و قابل‌نگهداری
کاور گرافیکی DevNA با عنوان «Clean Code»: اصول نوشتن کد تمیز و قابل‌نگهداری
فهرست مطالب
  1. کلین کد چیست و چرا اهمیت دارد؟
  2. نام‌گذاری معنادار
  3. توابع کوچک با یک مسئولیت
  4. بازآرایی یک تابع واقعی: قبل و بعد
  5. شرط‌های تودرتو را صاف کنید
  6. کامنت: چرا، نه چه
  7. تکرار نکنید، اما زود هم انتزاع نسازید
  8. مدیریت خطا بدون پنهان‌کاری
  9. اصول SOLID به زبان ساده
  10. فرمت و لینت را به ابزار بسپارید
  11. تست، شبکه‌ی ایمنی بازآرایی
  12. کلین کد در دوران دستیارهای هوش مصنوعی
  13. چک‌لیست بازبینی کد تمیز
  14. جمع‌بندی

کلین کد (Clean Code) یعنی کدی که فقط کار نمی‌کند، بلکه دیگران هم می‌توانند آن را سریع بخوانند، بفهمند و بدون ترس تغییر دهند. این اصطلاح با کتاب مشهور رابرت سی. مارتین رایج شد، اما ایده‌اش ساده و قدیمی است: بیشتر عمر یک نرم‌افزار صرف نگهداری آن می‌شود، نه نوشتن نسخه‌ی اول. در این راهنما اصول عملی کد تمیز را با مثال‌های پایتون مرور می‌کنیم؛ اصولی که در هر زبانی کاربرد دارند.

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

در راهنمای سبک رسمی پایتون، PEP 8، یکی از بینش‌های کلیدی گیدو ون روسوم، خالق پایتون، این‌طور نقل شده است: کد بسیار بیشتر از آنکه نوشته شود، خوانده می‌شود. هر بار که باگی را رفع می‌کنید یا قابلیتی اضافه می‌کنید، اول باید کد موجود را بفهمید.

مارتین فاولر این هزینه را با استعاره‌ی بدهی فنی (Technical Debt) توضیح می‌دهد: کیفیت پایین داخلی مثل وام است و «بهره‌اش» زمان اضافه‌ای است که هر تغییر بعدی می‌گیرد. نکته‌ی ظریف حرف فاولر این است که این بهره فقط وقتی پرداخت می‌شود که به آن کد دست بزنید؛ پس تمیز نگه داشتن بخش‌هایی که زیاد تغییر می‌کنند، بیشترین سود را دارد.

نام‌گذاری معنادار

نام خوب نیمی از مستندات است. مقایسه کنید:

# Hard to read
d = 30
lst = get(u)

# Self-explanatory
trial_period_days = 30
unpaid_invoices = fetch_unpaid_invoices(customer)

چند قاعده‌ی عملی:

  • نیت را بگویید، نه نوع را: users بهتر از user_list است و active_users از هر دو بهتر.
  • مقدارهای بولی را سؤالی نام بگذارید: is_active، has_permission، can_publish.
  • از مخفف‌های شخصی پرهیز کنید: cstmr_mgr را فقط نویسنده‌اش می‌فهمد.
  • واژگان یکدست داشته باشید: اگر در یک جا fetch نوشتید، جای دیگر برای همان کار get و retrieve ننویسید.
  • از قرارداد زبان پیروی کنید: در پایتون طبق PEP 8 نام توابع و متغیرها با حروف کوچک و خط زیر (snake_case) و نام کلاس‌ها با CapWords نوشته می‌شود.

طول نام هم باید با دامنه‌ی استفاده‌اش متناسب باشد. شمارنده‌ی یک حلقه‌ی سه‌خطی می‌تواند i باشد، اما متغیری که در چند تابع و فایل دیده می‌شود، به نامی کامل و توصیفی نیاز دارد. اگر برای یک تابع نام مناسبی پیدا نمی‌کنید، معمولاً نشانه‌ی آن است که تابع بیش از یک کار انجام می‌دهد.

توابع کوچک با یک مسئولیت

تابعی که هم داده را اعتبارسنجی می‌کند، هم در پایگاه داده ذخیره می‌کند و هم ایمیل می‌فرستد، سه دلیل برای تغییر دارد و تست کردنش سخت است. هر تابع باید یک کار را خوب انجام دهد.

راهنمای سبک پایتون گوگل عدد مشخصی می‌دهد: اگر تابعی از حدود ۴۰ خط بیشتر شد، فکر کنید آیا می‌شود آن را بدون آسیب به ساختار برنامه شکست. این یک قانون خشک نیست، اما زنگ خطر خوبی است. تعداد پارامترها هم مهم است؛ تابعی با شش پارامتر معمولاً یعنی چند مفهوم باید در یک ساختار داده کنار هم قرار بگیرند.

بازآرایی یک تابع واقعی: قبل و بعد

این تابع کار می‌کند، اما خواندنش عذاب است:

def calc(d):
    t = 0
    for i in d:
        if i["t"] == "b":
            t += i["p"] * i["q"] * 0.9
        else:
            t += i["p"] * i["q"]
    if t > 1000000:
        t = t - 50000
    return t

d، t و i چیزی نمی‌گویند، "b" معلوم نیست یعنی چه و 0.9 و 1000000 عدد جادویی (Magic Number) هستند. با چند بازآرایی (Refactoring) ساده از کاتالوگ فاولر، یعنی تغییر نام متغیر، جایگزینی عدد جادویی با ثابت و استخراج تابع، به این می‌رسیم:

WHOLESALE_DISCOUNT = 0.10
LARGE_ORDER_THRESHOLD = 1_000_000
LARGE_ORDER_REBATE = 50_000


def line_total(item: dict) -> float:
    subtotal = item["price"] * item["quantity"]
    if item["customer_type"] == "wholesale":
        return subtotal * (1 - WHOLESALE_DISCOUNT)
    return subtotal


def order_total(items: list[dict]) -> float:
    total = sum(line_total(item) for item in items)
    if total > LARGE_ORDER_THRESHOLD:
        total -= LARGE_ORDER_REBATE
    return total

منطق محاسبه در دو نسخه یکی است و فقط کلیدها و مقدارهای داده نام‌های گویاتری گرفته‌اند. اما حالا کد خودش می‌گوید چه قانونی را پیاده می‌کند، اگر نرخ تخفیف عوض شود فقط یک خط تغییر می‌کند و line_total را می‌شود جداگانه تست کرد.

یک نکته‌ی دیگر: این مثال برای سادگی از float استفاده می‌کند، اما در کد واقعی مبالغ پولی را با Decimal یا عدد صحیح (مثلاً به ریال) نگه دارید تا خطای گرد کردن اعشار در جمع‌ها دیده نشود.

شرط‌های تودرتو را صاف کنید

شرط‌های چندلایه ذهن خواننده را خسته می‌کنند. با بند محافظ (Guard Clause) حالت‌های استثنایی را زود برگردانید تا مسیر اصلی صاف بماند:

# Nested
def can_publish(article, user):
    if article is not None:
        if user.is_editor:
            if article.status == "reviewed":
                return True
    return False


# Flat, with guard clauses
def can_publish(article, user):
    if article is None:
        return False
    if not user.is_editor:
        return False
    return article.status == "reviewed"

کامنت: چرا، نه چه

کامنتی که همان کد را تکرار می‌کند، فقط نویز است و با اولین تغییر کد، دروغ می‌شود:

# Bad: repeats the code
i += 1  # increment i

# Good: explains a non-obvious decision
# The payment gateway rejects amounts with more than 2 decimals.
amount = round(amount, 2)

کامنت را برای چرایی تصمیم‌ها، محدودیت‌های بیرونی و هشدارها نگه دارید. کد کامنت‌شده را هم پاک کنید؛ Git تاریخچه را برایتان نگه می‌دارد.

تکرار نکنید، اما زود هم انتزاع نسازید

اصل DRY (Don't Repeat Yourself) می‌گوید هر دانش باید یک جا در کد تعریف شود. اما افراط در آن به انتزاع‌های زودهنگام و پیچیده می‌رسد. قاعده‌ی عملی بسیاری از تیم‌ها این است که بار سوم که الگویی تکرار شد، آن را به تابع یا ماژول مشترک تبدیل کنند. دو تکه کد شبیه هم که به دلایل متفاوت تغییر می‌کنند، لزوماً تکرار نیستند.

مدیریت خطا بدون پنهان‌کاری

  • خطا را قورت ندهید: except Exception: pass باگ را پنهان می‌کند و عیب‌یابی را بسیار دشوار می‌کند.
  • خطای مشخص بگیرید: فقط استثنایی را بگیرید که می‌دانید چطور مدیریتش کنید.
  • زود شکست بخورید: ورودی نامعتبر را همان ابتدای تابع رد کنید، نه سه لایه پایین‌تر.
  • پیام خطا را کامل بنویسید: مقدار نامعتبر و انتظار درست را در پیام بگذارید.

اصول SOLID به زبان ساده

وقتی از سطح تابع به سطح کلاس و ماژول می‌رسید، پنج اصل مشهور به SOLID راهنمای خوبی برای طراحی تمیز است:

اصل معنای عملی
تک‌مسئولیتی (Single Responsibility) هر کلاس یا ماژول فقط یک دلیل برای تغییر داشته باشد
باز و بسته (Open/Closed) برای افزودن رفتار تازه، کد جدید اضافه کنید، نه اینکه کد پایدار را دست‌کاری کنید
جایگزینی لیسکوف (Liskov Substitution) هر زیرکلاس باید بی‌دردسر جای کلاس والد بنشیند
تفکیک رابط (Interface Segregation) به‌جای یک رابط بزرگ، چند رابط کوچک و متمرکز بسازید
وارونگی وابستگی (Dependency Inversion) منطق اصلی به انتزاع وابسته باشد، نه به جزئیاتی مثل یک پایگاه داده‌ی مشخص

این اصول ابزار فکر کردن‌اند، نه قانون. در یک اسکریپت صدخطی، پیاده‌سازی همه‌ی آن‌ها فقط پیچیدگی اضافه می‌کند. هرچه پروژه بزرگ‌تر و تیم پرجمعیت‌تر شود، ارزششان بیشتر خودش را نشان می‌دهد؛ به‌خصوص وارونگی وابستگی که تست‌نویسی را بسیار ساده‌تر می‌کند، چون می‌توانید به‌جای سرویس واقعی، نسخه‌ی جعلی آن را به کد بدهید.

فرمت و لینت را به ابزار بسپارید

بحث درباره‌ی فاصله و جای آکولاد در بازبینی کد، وقت تلف کردن است. این کارها را به ابزار بسپارید:

زبان فرمت‌کننده لینتر
Python Black یا ruff format Ruff
JavaScript / TypeScript Prettier ESLint
Go gofmt go vet

این ابزارها را هم در ویرایشگر و هم در پایپ‌لاین CI اجرا کنید تا کدی که قاعده را رعایت نمی‌کند، اصلاً ادغام نشود؛ آموزش CI/CD با GitHub Actions نحوه‌ی راه‌اندازی آن را نشان می‌دهد.

تست، شبکه‌ی ایمنی بازآرایی

بازآرایی یعنی تغییر ساختار کد بدون تغییر رفتار آن. بدون تست خودکار، راهی برای اطمینان از «بدون تغییر رفتار» ندارید. پیش از تمیز کردن یک بخش قدیمی، چند تست برای رفتار فعلی‌اش بنویسید، بعد با گام‌های کوچک پیش بروید و بعد از هر گام تست‌ها را اجرا کنید. هر گام را هم جداگانه در Git ثبت کنید تا اگر چیزی خراب شد، بدانید کدام تغییر مقصر بود.

قاعده‌ی پیشاهنگی (Boy Scout Rule) هم خلاصه‌ی خوبی است: کد را کمی تمیزتر از زمانی که تحویل گرفتید، تحویل دهید.

کلین کد در دوران دستیارهای هوش مصنوعی

ابزارهای تولید کد با هوش مصنوعی سرعت نوشتن را بالا برده‌اند، اما مسئولیت خوانایی و درستی کد همچنان با شماست. کدی را که دستیار پیشنهاد می‌دهد، مثل کد یک هم‌تیمی تازه‌وارد بازبینی کنید: نام‌ها، تکرارها و مدیریت خطا را بسنجید. در راهنمای بهترین ابزارهای هوش مصنوعی برای برنامه‌نویسی به نقاط قوت و ضعف این ابزارها پرداخته‌ایم.

چک‌لیست بازبینی کد تمیز

پرسش اگر پاسخ «نه» است
نام‌ها بدون کامنت منظور را می‌رسانند؟ تغییر نام دهید
هر تابع یک کار انجام می‌دهد؟ تابع را بشکنید
عدد یا رشته‌ی جادویی وجود ندارد؟ ثابت با نام معنادار بسازید
تودرتویی شرط‌ها بیشتر از دو سطح نیست؟ از بند محافظ استفاده کنید
خطاها بی‌صدا نادیده گرفته نمی‌شوند؟ خطای مشخص بگیرید یا بالا بفرستید
برای رفتار مهم تست وجود دارد؟ پیش از ادغام تست بنویسید

جمع‌بندی

کد تمیز محصول یک بازنویسی بزرگ نیست؛ نتیجه‌ی عادت‌های کوچکی است که هر روز تکرار می‌شوند. اگر تازه شروع کرده‌اید، مثال‌های آموزش پایتون از صفر را با همین چک‌لیست بازنویسی کنید و تغییرات را با Git و GitHub ثبت کنید تا تفاوت قبل و بعد را ببینید.

$ devna rate --article

—
هنوز رأیی ثبت نشده
  1. ۵۰
  2. ۴۰
  3. ۳۰
  4. ۲۰
  5. ۱۰

این مطلب چقدر به کارتان آمد؟

روی ستاره‌ها بزنید

واکنش شما

اولین نفری باشید که واکنش نشان می‌دهد.

پرسش‌های پرتکرار

آیا رعایت کلین کد سرعت توسعه را کم می‌کند؟

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

آیا برای کلین کد باید کدهای قدیمی پروژه را بازنویسی کرد؟

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

آیا کامنت زیاد نشانه‌ی کد تمیز است؟

نه لزوماً. کد خوب با نام‌های روشن خودش توضیح می‌دهد چه می‌کند. کامنت برای توضیح چرایی تصمیم‌ها، محدودیت‌ها و نکته‌های غیربدیهی است.

آیا ابزاری برای رعایت خودکار اصول کد تمیز وجود دارد؟

بله. فرمت‌کننده‌ها و لینترها مثل Ruff و Black برای پایتون یا Prettier و ESLint برای جاوااسکریپت بخشی از قواعد را خودکار می‌کنند، اما نام‌گذاری خوب و طراحی درست همچنان کار انسان است.

منابع

  1. PEP 8 – Style Guide for Python Code
  2. Google Python Style Guide
  3. Martin Fowler – Catalog of Refactorings
  4. Martin Fowler – Technical Debt

خطایی در این مطلب دیدید؟ به تحریریه گزارش دهید؛ اصلاحیه‌ها طبق اصول تحریریه ثبت می‌شوند.

دیدگاه‌ها

۰/۲٬۰۰۰

دیدگاه‌ها پس از بررسی تحریریه منتشر می‌شوند. توهین، تبلیغ و لینک‌های بی‌ربط حذف می‌شوند؛ نقد فنی و مستند همیشه خوش‌آمد است.

$ comments --count۰

هنوز کسی چیزی ننوشته. اولین دیدگاه را شما ثبت کنید.

مطالب مرتبط