آموزش نوشتن کد تمیز در پایتون (قواعد PEP 8 و فراتر از آن)

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

بسیاری از ما در ابتدای مسیر برنامه‌نویسی، تمام تمرکزمان را بر روی یک هدف می‌گذاریم: کدی بنویسیم که «کار کند». ما ساعت‌ها وقت صرف می‌کنیم تا الگوریتم درستی را پیدا کرده و باگ‌ها را برطرف کنیم و در نهایت، وقتی برنامه بدون خطا اجرا می‌شود، احساس پیروزی می‌کنیم. اما این تنها نیمی از ماجراست.

واقعیت این است که ما به عنوان توسعه‌دهنده، زمان بسیار بیشتری را صرف «خواندن» کد می‌کنیم تا «نوشتن» آن. ما کدهای همکارانمان را می‌خوانیم، کدهای کتابخانه‌های مختلف را بررسی می‌کنیم و از همه مهم‌تر، کدی را می‌خوانیم که خودمان شش ماه پیش نوشته‌ایم!

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

این کد، یک «بدهی فنی» (Technical Debt) است که در آینده، با بهره‌های سنگین، زمان، انرژی و پول شما و تیمتان را هدر خواهد داد.

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

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

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

پیشنهاد مطالعه: مدت زمان یادگیری پایتون چه قدر است؟ (راهنمای واقع بینانه در سال 2025)

پیشنهاد مطالعه: معرفی 10 پروژه مبتدی پایتون برای افزایش مهارت و شانس استخدام

PEP 8، انجیل کدنویسی خوانا در پایتون

PEP 8 (Python Enhancement Proposal 8) یک سند راهنمای سبک کدنویسی (Style Guide) است که توسط گویدو ون روسوم، خالق پایتون، و همکارانش نوشته شده است.

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

اصول نام‌گذاری (Naming Conventions): هنر انتخاب نام درست نام‌هایی که برای متغیرها، توابع و کلاس‌های خود انتخاب می‌کنید، مهم‌ترین نقش را در خوانایی کد شما ایفا می‌کنند. PEP 8 یک استاندارد مشخص برای این کار ارائه می‌دهد:

• متغیرها، توابع و متدها: باید با حروف کوچک نوشته شوند و کلمات با آندرلاین (_) از هم جدا شوند. این سبک که به آن snake_case می‌گویند، خوانایی را به شدت افزایش می‌دهد.

  • بد: myvariable, myVariable, MyVariable

  • خوب: my_variable, user_name, calculate_average

• کلاس‌ها: باید با سبک PascalCase (یا CapWords) نام‌گذاری شوند. یعنی حرف اول هر کلمه بزرگ باشد و هیچ جداکننده‌ای بین کلمات وجود نداشته باشد.

  • بد: myclass, my_class

  • خوب: MyClass, DatabaseConnection, UserPermission

• ثابت‌ها (Constants): متغیرهایی که مقدارشان در طول برنامه تغییر نمی‌کند، باید با حروف بزرگ و با جداکننده آندرلاین نوشته شوند.

  • خوب: MAX_OVERFLOW, DEFAULT_TIMEOUT

تورفتگی و طول خطوط (Indentation & Line Length): ساختار بصری کد پایتون برای تعریف بلوک‌های کد (مانند بدنه‌ی یک تابع یا حلقه) از تورفتگی استفاده می‌کند. این یکی از ویژگی‌های منحصر به فرد پایتون است که به خوانایی آن کمک می‌کند.

• تورفتگی: استاندارد مطلق در PEP 8، استفاده از 4 فاصله (Space) برای هر سطح از تورفتگی است. استفاده از Tab به شدت نهی شده است، زیرا ممکن است در ویرایشگرهای مختلف، به شکل متفاوتی نمایش داده شود.

• طول خطوط: PEP 8 توصیه می‌کند که طول هر خط کد، حداکثر 79 کاراکتر باشد. برای داک‌استرینگ‌ها و کامنت‌ها این محدودیت 72 کاراکتر است. دلیل این محدودیت، تاریخی و عملی است. این کار به شما اجازه می‌دهد چندین فایل را در کنار هم باز کنید و از اسکرول افقی جلوگیری می‌کند. اگر یک خط کد طولانی شد، باید آن را به صورت خوانا بشکنید. پایتون اجازه می‌دهد عبارات داخل پرانتز، کروشه و آکولاد را به راحتی در چندین خط بنویسید.

کامنت‌گذاری موثر: توضیح «چرا»، نه «چه» یک اشتباه رایج در میان مبتدیان، نوشتن کامنت‌های بیهوده است. یک کد تمیز پایتون، باید به خودی خود گویا باشد (Self-documenting). کامنت‌ها نباید کاری که کد انجام می‌دهد را توضیح دهند؛ کد خودش باید این را بگوید. کامنت‌ها باید «چرا»ی پشت یک تصمیم پیچیده یا یک منطق غیربدیهی را توضیح دهند.

• کامنت بد: x = x + 1 # Add one to x (این کامنت هیچ ارزشی ندارد).

• کامنت خوب: retries += 1 # Increment retry counter to handle transient network errors (این کامنت، دلیل وجود این خط کد را توضیح می‌دهد).

داک‌استرینگ‌ها (Docstrings): داک‌استرینگ‌ها نوع خاصی از کامنت هستند که در اولین خط یک ماژول، کلاس یا تابع قرار می‌گیرند و هدف و نحوه‌ی استفاده از آن را توضیح می‌دهند. این‌ها مستندات کد شما هستند و ابزارهای خودکار می‌توانند از آن‌ها برای ساخت مستندات پروژه استفاده کنند. همیشه برای تمام توابع و کلاس‌های عمومی خود، داک‌استرینگ بنویسید.

فضای سفید (Whitespace): نقطه‌گذاری در دنیای کد استفاده هوشمندانه و یکدست از فضای سفید، تاثیر شگرفی بر خوانایی کد دارد.

• اطراف عملگرهای ریاضی، مقایسه‌ای و تخصیص، از یک فاصله در هر طرف استفاده کنید: x = 1, y = x * 2.

• بعد از کاما (,) در لیست‌ها، دیکشنری‌ها و آرگومان‌های توابع، یک فاصله قرار دهید: my_list = [1, 2, 3].

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

 اصول نوشتن توابع و ساختارهای کنترلی تمیز

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

توابع باید یک کار، و فقط یک کار را به خوبی انجام دهند این اصل که به آن اصل مسئولیت واحد (Single Responsibility Principle) می‌گویند، مهم‌ترین قانون در طراحی نرم‌افزار است.

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

• get_data_from_database()

• process_user_data()

• save_results_to_file() توابع کوچک و متمرکز، به راحتی قابل درک، تست و استفاده مجدد هستند. به عنوان یک قانون سرانگشتی، اگر یک تابع بیش از 15-20 خط کد دارد، یا اگر نمی‌توانید در یک جمله کوتاه و بدون استفاده از کلمه «و»، کاری که انجام می‌دهد را توضیح دهید، احتمالاً باید آن را به توابع کوچکتر بشکنید.

انتخاب نام‌های گویا و معنادار برای توابع نام یک تابع باید مانند یک تیتر خبری، به وضوح کاری که انجام می‌دهد را بیان کند. از نام‌های تک‌حرفی یا مبهم پرهیز کنید. نام تابع باید به صورت یک فعل یا عبارت فعلی باشد.

• بد: proc_data(d), handle(), f()

• خوب: calculate_tax_for_invoice(invoice_data), send_welcome_email_to_new_user(user_object), is_password_strong(password_string) یک نام خوب، نیاز به خواندن بدنه تابع برای درک کارکرد آن را از بین می‌برد.

کاهش تعداد آرگومان‌های توابع توابعی که تعداد زیادی آرگومان ورودی دارند (مثلاً بیشتر از ۳ یا ۴ آرگومان)، به سختی قابل استفاده و به خاطر سپردن هستند.

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

شاید بتوانید چندین آرگومان مرتبط را در یک کلاس یا یک دیکشنری بسته‌بندی کرده و به جای آن‌ها، یک شیء واحد را به تابع پاس دهید.

پرهیز از تودرتوی عمیق و استفاده از گارد کلاز (Guard Clause) بلوک‌های کد if/else که به صورت عمیق در هم تودرتو شده‌اند، کابوس خوانایی کد هستند. دنبال کردن منطق در چنین کدهایی بسیار دشوار است.

کد بد (تودرتوی عمیق):

def process_payment(user, card_info):
    if user.is_active:
        if card_info.is_valid:
            if card_info.balance > 100:
                # process the payment...
            else:
                return "Error: Insufficient balance"
        else:
            return "Error: Invalid card"
    else:
        return "Error: User is not active"

def process_payment_clean(user, card_info):
    if not user.is_active:
        return "Error: User is not active"
    if not card_info.is_valid:
        return "Error: Invalid card"
    if card_info.balance <= 100:
        return "Error: Insufficient balance"
    # process the payment...