حتماً برای شما هم پیش آمده که ساعت‌ها وقت خود را صرف بحث با هم‌تیمی‌هایتان کنید که آیا برای فاصله مجاز در کدها باید از Tab استفاده کرد یا Space؟ یا اینکه ویرگول‌ها و پرانتزها در پایتون باید دقیقاً کجا قرار بگیرند تا اصول PEP 8 رعایت شود؟

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

پایتون برای پایان دادن به این فرآیند فرسایشی، ابزارهایی هوشمند به نام لایترها (Linters) و فرمترها (Formatters) را در اختیار ما می‌گذارد؛ پلیس‌های مخفی و مهربانی که کدهای شما را ثانیه به ثانیه بررسی و استانداردسازی می‌کنند.

در این درس یاد می‌گیرید که چطور این ابزارهای خودکار را یک‌بار برای همیشه در پروژه و محیط توسعه خود (مانند VS Code یا PyCharm) پیکربندی کنید.

با هم بررسی می‌کنیم که چگونه ابزارهای مدرنی مثل Ruff و Black می‌توانند تمام خطاهای نگارشی، متغیرهای استفاده‌نشده و کثیفی‌های ظاهری کد را در کسری از ثانیه و تنها با فشردن دکمه Save اصلاح کنند.

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

تفاوت بنیادین لایتر (Linter) و فرمتر (Formatter) در چیست؟

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

لایتر؛ پلیس تیزبین کدهای شما

لایتر (Linter) ابزاری است که خطوط کد را برای پیدا کردن باگ‌های احتمالی، خطاهای ساختاری و نقض استانداردهای برنامه نویسی پایتون اسکن می‌کند. لایتر به منطق و کیفیت فنی کار توجه دارد. این ابزار کدهای شما را بدون اینکه اجرا کند، می‌خواند و تحلیل می‌کند. به این فرآیند، تحلیل ایستا (Static Analysis) می‌گویند.

وقتی یک متغیر را تعریف می‌کنید اما هیچ‌وقت از آن در طول برنامه استفاده نمی‌کنید، لایتر به شما هشدار می‌دهد. اگر کتابخانه‌ای را ایمپورت کنید که نیازی به آن نیست، باز هم لایتر دستش را بالا می‌برد. این ابزار حتی خطاهای خطرناکی مانند استفاده از متغیرهای تعریف‌نشده یا کدهای غیرقابل دسترس (Unreachable Code) را قبل از اجرای برنامه به شما گوشزد می‌کند. ابزارهایی مانند Flake8 یا Ruff نمونه‌های برجسته‌ای از لایترهای دنیای پایتون هستند.

فرمتر؛ آرایشگر مهربان کدهای شما

فرمتر (Formatter) هیچ کاری با باگ‌ها، متغیرهای رها شده یا منطق برنامه ندارد. تمرکز فرمتر کاملاً روی ظاهر، چیدمان و زیبایی بصری کدها است. فرمتر تضمین می‌کند که تمام اعضای تیم از یک قانون ظاهری واحد پیروی کنند.

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

ابزار محبوب Black یا بخش فرمتر Ruff نمونه‌های کاملی از این ابزارها هستند. فرمتر کدهای شما را بازنویسی می‌کند تا اصول سبک نگارش پایتون یا همان استاندارد PEP 8 دقیقاً رعایت شود.

جدول مقایسه لایتر و فرمتر در یک نگاه

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

ویژگی لایتر (Linter) فرمتر (Formatter)
تمرکز اصلی کیفیت فنی، امنیت و کشف باگ‌های پنهان زیبایی، چیدمان و یکدستی ظاهر کدها
نوع عمل هشدار دادن به برنامه نویس و گزارش خطاها تغییر دادن و بازنویسی خودکار چیدمان متن کد
مثال واقعی شناسایی متغیرهای بلااستفاده یا اشتباهات منطقی تنظیم فاصله‌ها (Spaces) و شکستن خطوط طولانی

استفاده هم‌زمان از ابزارهای مدیریت خطا و ابزارهای استانداردسازی خودکار کد، شما را از بحث‌های فرسایشی درباره ظاهر کدها در تیم نجات می‌دهد. این ترکیب هوشمندانه زمان بررسی کد (Code Review) را به شدت کاهش می‌دهد. تمرکز شما با این روش فقط روی حل مسائل اصلی کسب‌وکار قرار می‌گیرد.

آشنایی با استاندارد PEP 8؛ قانون اساسی زیبایی کد در پایتون

استاندارد PEP 8 مخفف Python Enhancement Proposal شماره 8 است. این سند رسمی، مجموعه قواعد و دستورالعمل‌هایی را مشخص می‌کند که هدف آن‌ها نوشتن کدهایی یکدست، خوانا و زیبا در زبان پایتون است. گویدو وان روسوم، خالق پایتون، در این سند جمله‌ای کلیدی دارد: «کدها بسیار بیشتر از آنکه نوشته شوند، خوانده می‌شوند.» این استاندارد نوشته شده است تا فرآیند خواندن و درک کدهای دیگران را برای شما آسان کند.

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

قواعد نام‌گذاری متغیرها و توابع (Naming Conventions)

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

توابع و متغیرها: باید از سبک snake_case استفاده کنید. تمام حروف به صورت کوچک نوشته می‌شوند و کلمات با خط تیره زیرین (Underscore) از هم جدا می‌شوند؛ مانند calculate_total_price.

کلاس‌ها: باید از سبک PascalCase یا CapWords استفاده کنید. حرف اول هر کلمه باید بزرگ باشد و هیچ فاصله‌ای بین کلمات وجود ندارد؛ مانند UserProfileManager.

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

مدیریت فاصله‌ها و تورفتگی‌ها (Indentation & Whitespace)

تنظیم درست فاصله‌ها، ساختار منطقی کدهای پایتون را شکل می‌دهد. نقض این قوانین ظاهر کد را به شدت آشفته می‌کند:

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

طول خطوط کلاسی: حداکثر طول مجاز برای هر خط کد، 79 کاراکتر است. برای کامنت‌ها و داک‌استرینگ‌ها این عدد به 72 کاراکتر کاهش می‌یابد. خطوط طولانی خوانایی کد را در مانیتورهای کوچک یا هنگام باز کردن دو کد در کنار هم (Split View) به شدت کاهش می‌دهند.

فاصله اطراف عملگرها: اطراف عملگرهای محاسباتی و انتسابی باید دقیقاً یک فاصله بگذارید؛ مانند x = y + 5. اما در زمان تعریف آرگومان‌های پیش‌فرض برای توابع، نباید از فاصله استفاده کنید؛ مانند def connect(timeout=30):.

خطوط خالی؛ ایجاد فضای تنفس برای کد

استفاده به جا از خطوط خالی (Blank Lines) به کدهای شما ساختار بصری منسجمی می‌دهد. توابع و کلاس‌های سطح بالا (Top-level) باید با دو خط خالی از یکدیگر جدا شوند. متدهای داخلی یک کلاس نیز باید با یک خط خالی از هم متمایز شوند. درون توابع هم می‌توانید برای جداسازی منطقی بخش‌های مختلف (مثل جداسازی بخش محاسبات از بخش بازگشت داده) از یک خط خالی استفاده کنید.

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

معرفی ابزارهای سنتی در برابر ابزارهای مدرن (Flake8 و Black در برابر Ruff)

اکوسیستم پایتون در سال‌های اخیر شاهد جهشی بزرگ در زمینه ابزارهای توسعه بوده است. سال‌ها توسعه‌دهندگان برای مدیریت کیفیت کدهای خود مجبور بودند چندین ابزار مختلف را در کنار هم بکار بگیرند. ترکیب ابزارهای سنتی مانند Flake8 و Black ترکیب استانداردی بود که در اکثر پروژه‌ها دیده می‌شد. ظهور ابزارهای مدرن و همه‌کاره، این بازی را به طور کامل تغییر داد.

ابزارهای سنتی؛ ترکیب Flake8 و Black

در رویکرد سنتی، هر ابزار فقط یک کار را انجام می‌داد. ابزار Flake8 به عنوان یک لایتر وظیفه بررسی باگ‌ها و نقض قوانین PEP 8 را بر عهده داشت. این ابزار کدهای کثیف را گزارش می‌داد اما خودش آن‌ها را اصلاح نمی‌کرد. در کنار آن، ابزار Black به عنوان یک فرمتر سخت‌گیر وارد عمل می‌شد. این ابزار بدون اجازه شما، چیدمان کدها را بازنویسی می‌کرد تا کاملاً یکدست شوند.

این ترکیب با وجود کارآمدی، سه مشکل اساسی برای پروژه‌ها ایجاد می‌کرد:

  • سرعت پایین اجرا: این ابزارها با زبان پایتون نوشته شده بودند. اجرای آن‌ها روی پروژه‌های بزرگ با هزاران خط کد، زمان زیادی می‌برد.
  • تنظیمات چندگانه: شما مجبور بودید فایل‌های پیکربندی مجزایی برای هر کدام بسازید. هماهنگ کردن این ابزارها با هم گاهی باعث تداخل می‌شد.
  • تعدد پکیج‌ها: برای داشتن یک محیط کامل، باید ابزارهای دیگری مثل isort (برای مرتب‌سازی ایمپورت‌ها) را هم نصب می‌کردید. این موضوع تعداد وابستگی‌های پروژه (Dependencies) را بالا می‌برد.

Ruff؛ پادشاه مدرن و همه‌کاره پایتون

ابزار Ruff یک لایتر و فرمتر فوق‌العاده سریع است که با زبان جاست (Rust) نوشته شده است. این ابزار انقلابی در دنیای پایتون ایجاد کرد. Ruff ادعا می‌کند که بین ۱۰ تا ۱۰۰ برابر سریع‌تر از ابزارهای قدیمی عمل می‌کند. این ابزار تمام وظایف Flake8، Black، isort و ده‌ها پلاگین دیگر را به تنهایی انجام می‌دهد.

استفاده از Ruff به شما اجازه می‌دهد تمام ابزارهای سنتی را از پروژه خود حذف کنید. این ابزار به جای داشتن چندین فایل پیکربندی مختلف، فقط با یک فایل pyproject.toml تنظیم می‌شود. Ruff نه تنها خطاهای کد را شناسایی می‌کند، بلکه به کمک قابلیت اصلاح خودکار (Autofix)، صدها خطای نگارشی و منطقی را در کسری از ثانیه برطرف می‌کند.

جدول مقایسه ابزارهای سنتی و مدرن

تفاوت عملکرد و ساختار این دو رویکرد را در جدول زیر بررسی کنید:

شاخص ارزیابی رویکرد سنتی (Flake8 + Black) رویکرد مدرن (Ruff)
زبان توسعه ابزار پایتون (کُندتر در پردازش‌های سنگین) راست / Rust (فوق‌العاده سریع و بهینه)
تعداد ابزارهای مورد نیاز حداقل ۳ ابزار مستقل (Flake8, Black, isort) ۱ ابزار واحد و جامع برای تمام وظایف
سرعت اجرا در پروژه‌های بزرگ چند ثانیه تا چند دقیقه چند میلی‌ثانیه (تقریباً آنی)
مدیریت پیکربندی فایل‌های مجزا (.flake8, black.toml) یکپارچه در فایل استاندارد pyproject.toml

کوچ کردن به سمت ابزارهای مدرن مانند Ruff، زمان اجرای تست‌های خودکار و فرآیند CI/CD پروژه شما را به شدت کاهش می‌دهد. این ابزار به دلیل سرعت سرسام‌آور خود، بازخوردها را همان لحظه تایپ کد به شما نشان می‌دهد. این ویژگی به حفظ تمرکز ذهنی برنامه‌نویس در طول روز کمک شایانی می‌کند.

آموزش گام‌به‌گام پیکربندی ابزار Ruff (پادشاه مدرن لایترها) در پروژه

راه‌اندازی ابزار Ruff در پروژه بسیار ساده است و تمام تنظیمات آن درون فایل پیکربندی استاندارد پایتون یعنی pyproject.toml قرار می‌گیرد. این فایل در ریشه (Root) پروژه شما ساخته می‌شود. با دنبال کردن گام‌های زیر، این ابزار را به صورت حرفه‌ای در پروژه خود مستقر کنید.

گام اول: نصب ابزار Ruff

ابتدا باید این ابزار را در محیط مجازی (Virtual Environment) پروژه خود نصب کنید. با توجه به ابزار مدیریت پکیجی که استفاده می‌کنید، یکی از دستورات زیر را در ترمینال اجرا کنید:

# نصب با استفاده از pip
pip install ruff

# نصب با استفاده از poetry
poetry add ruff --group dev

گام دوم: ساخت و تنظیم فایل pyproject.toml

یک فایل به نام pyproject.toml در پوشه اصلی پروژه ایجاد کنید. تنظیمات زیر یک پیکربندی استاندارد، سخت‌گیرانه و بهینه را برای پروژه‌های جنگو و پایتون پیاده‌سازی می‌کند. این خطوط را درون فایل قرار دهید:

[tool.ruff]
# تعیین حداقل نسخه پایتون پروژه
target-version = "py310"

# تنظیم حداکثر طول خطوط بر اساس استاندارد PEP 8
line-length = 79

# مشخص کردن پوشه‌هایی که روف نباید آن‌ها را بررسی کند
exclude = [
    ".git",
    ".venv",
    "migrations",
]

[tool.ruff.lint]
# فعال‌سازی دسته‌بندی قوانین مختلف
# E/W: خطاهای عمومی و نگارشی PEP 8
# F: خطاهای منطقی و باگ‌های احتمالی (Flake8)
# I: مرتب‌سازی خودکار ایمپورت‌ها (isort)
# DJ: استانداردهای مخصوص فریم‌ورک جنگو
select = ["E", "W", "F", "I", "DJ"]

# چشم‌پوشی از قوانین خاص در صورت نیاز
ignore = []

[tool.ruff.lint.isort]
# ترکیب کردن ایمپورت‌های مربوط به یک کتابخانه در یک خط
combine-as-imports = true

گام سوم: اجرای Ruff از طریق ترمینال

پس از ذخیره فایل تنظیمات، با استفاده از ترمینال می‌توانید کدهای پروژه را اسکن و اصلاح کنید. دستورات زیر دو عملیات اصلی روف را انجام می‌دهند:

  • بررسی و شناسایی خطاها (Lint): برای اسکن کردن تمام فایل‌های پروژه، دستور زیر را اجرا کنید. روف تمام خطاهای نگارشی، متغیرهای رها شده و ایرادات منطقی را به همراه شماره خط به شما گزارش می‌دهد:
ruff check .
  • اصلاح خودکار خطاها (Autofix): برای اینکه روف تمام خطاهایی که قابلیت اصلاح خودکار دارند (مانند حذف ایمپورت‌های بلااستفاده، مرتب‌سازی ایمپورت‌ها و تنظیم برخی فاصله‌ها) را فوراً درست کند، از پرچم --fix استفاده کنید:
ruff check . --fix

گام چهارم: استفاده از فرمتر Ruff

ابزار Ruff در نسخه‌های جدید خود یک فرمتر اختصاصی و فوق‌العاده سریع را هم معرفی کرده است که جایگزین Black می‌شود. برای مرتب کردن ظاهر تمام کدهای پروژه بر اساس قواعد تنظیم شده در گام دوم، دستور زیر را اجرا کنید:

ruff format .

با اجرای این دستور، چیدمان تمام خطوط، پرانتزها و فاصله‌های پروژه در کمتر از چند میلی‌ثانیه کاملاً استاندارد و یکدست می‌شود. ساختار فایل تنظیمات واحد به شما کمک می‌کند تا این ابزار را به راحتی در سیستم‌های کلود یا ابزارهای تست خودکار (CI/CD) نیز بدون هیچ پکیج اضافه‌ای اجرا کنید.

تنظیم خودکار ابزارها در محیط توسعه (VS Code و PyCharm) هنگام ذخیره فایل

اجرای دستی دستورات لایتر و فرمتر در ترمینال پس از تغییر هر خط کد، فرآیندی فرسایشی است و تمرکز شما را از بین می‌برد. بهترین راهکار، متصل کردن ابزار Ruff به ویرایشگر کد است تا با هر بار فشردن کلیدهای Ctrl + S (یا Cmd + S در مک)، عملیات اصلاح و فرمت کد در کسری از ثانیه انجام شود. در ادامه، نحوه تنظیم این قابلیت را در دو محیط توسعه VS Code و PyCharm بررسی کنید.

راهنمایی تنظیم خودکار در Visual Studio Code

محیط توسعه VS Code به دلیل داشتن افزونه‌های رسمی و پویایی بالا، هماهنگی فوق‌العاده‌ای با Ruff دارد. برای فعال‌سازی این افزونه، مراحل زیر را طی کنید:

  • نصب افزونه: به بخش Extensions (کلیدهای میانبر Ctrl + Shift + X) بروید و عبارت Ruff (افزونه رسمی توسعه داده شده توسط Astral Software) را جستجو و نصب کنید.
  • تنظیم به عنوان فرمتر پیش‌فرض: یک فایل پایتون را باز کنید، در فضای خالی راست‌کلیک کرده و گزینه Format Document With... را انتخاب کنید. سپس از لیست باز شده، گزینه Ruff را انتخاب کنید.
  • تنظیمات خودکار هنگام ذخیره (Save): برای اینکه این فرآیند کاملاً خودکار شود، فایل تنظیمات سراسری وی‌اس‌کد (settings.json) را باز کرده و خطوط زیر را به آن اضافه کنید:
{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "always",
            "source.organizeImports.ruff": "always"
        }
    }
}

با اعمال این تنظیمات، هر زمان که فایلی را ذخیره کنید، افزونه Ruff ابتدا خطاهای نگارشی قابل حل را برطرف می‌کند (fixAll)، سپس ایمپورت‌ها را مرتب می‌سازد (organizeImports) و در نهایت ظاهر کد را کاملاً مرتب و استاندارد می‌کند (formatOnSave).

راهنمایی تنظیم خودکار در PyCharm

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

  • نصب پلاگین: از منوی بالا به مسیر File > Settings (در مک PyCharm > Preferences) بروید. بخش Plugins را انتخاب کرده، عبارت Ruff را جستجو و آن را نصب کنید. پس از نصب، یک‌بار ویرایشگر را ری‌استارت کنید.
  • تنظیم مسیر اجرایی: به مسیر Settings > Tools > Ruff بروید. مطمئن شوید پلاگین به صورت خودکار مسیر فایل اجرایی روف را در محیط مجازی پروژه شما شناسایی کرده است.
  • فعال‌سازی قابلیت Run on Save: در همان پنجره تنظیمات Ruff، گزینه‌های زیر را تیک بزنید:

Run ruff check on save: برای بررسی و رفع خطاهای منطقی و نگارشی هنگام ذخیره فایل.

Run ruff format on save: برای مرتب‌سازی چیدمان و ساختار ظاهری کد هنگام ذخیره فایل.

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

استفاده از Pre-commit Hooks برای جلوگیری از ورود کدهای کثیف به ریپازیتوری

تنظیم لایترها و فرمترها در ویرایشگر کد عالی است، اما هنوز یک لایه حفاظتی دیگر برای تضمین صددرصدی سلامت کدها در تیم نیاز دارید. همیشه این احتمال وجود دارد که یکی از توسعه‌دهندگان، افزونه ویرایشگر خود را غیرفعال کرده باشد یا فایلی را بدون فرمت کردن ذخیره کند. ابزار pre-commit به عنوان آخرین خط دفاعی پروژه، در لایه گیت (Git) قرار می‌گیرد و به هیچ کدی اجازه نمی‌دهد قبل از تایید ناییدیه استانداردها، وارد ریپازیتوری شود.

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

گام اول: نصب ابزار pre-commit در پروژه

این ابزار را باید به عنوان یک وابستگی توسعه (Development Dependency) در محیط مجازی خود نصب کنید. دستور مناسب با ابزار مدیریت پکیج خود را در ترمینال اجرا کنید:

# نصب با استفاده از pip
pip install pre-commit

# نصب با استفاده از poetry
poetry add pre-commit --group dev

گام دوم: ساخت فایل پیکربندی pre-commit-config.yaml

یک فایل به نام .pre-commit-config.yaml (دقت کنید که نقطه در ابتدای اسم فایل قرار دارد) در ریشه اصلی پروژه بسازید. این فایل به گیت می‌گوید چه ابزارهایی را باید قبل از هر کامیت روی کدهای تغییریافته اجرا کند. ساختار استاندارد و بهینه زیر را درون فایل قرار دهید:

# تعیین مخازن و ابزارهای مورد نیاز برای بررسی کدهای پایتون
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0  # استفاده از آخرین نسخه پایدار ابزار روف
    hooks:
      # اجرای بخش لایتر روف برای بررسی و اصلاح خودکار باگ‌ها
      - id: ruff
        args: [ --fix ]
      # اجرای بخش فرمتر روف برای تنظیم چیدمان ظاهری کدها
      - id: ruff-format

گام سوم: فعال‌سازی و تزریق هوک‌ها به گیت

ساختن فایل تنظیمات به تنهایی کافی نیست؛ باید به سیستم گیت محلی خود دستور دهید که این فایل را بخواند و اجرا کند. برای متصل کردن ابزار به گیت، دستور زیر را در ترمینال پروژه اجرا کنید:

pre-commit install

با اجرای این دستور، پیغام pre-commit installed at .git/hooks/pre-commit را دریافت می‌کنید. این یعنی پلیس مخفی گیت در پروژه شما بیدار شده است.

تجربه کاربری در زمان ثبت کدهای جدید

از این پس، هر زمان که کدی را تغییر دهید و بخواهید آن را با دستور git commit -m "my updates" ثبت کنید، ابزار pre-commit فوراً دست‌به‌کار می‌شود. روف تمام فایل‌های استیج‌شده (Staged Files) را اسکن می‌کند.

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

در این حالت، شما کافی است فایل‌های اصلاح‌شده را دوباره با دستور git add اضافه کرده و مجدداً کامیت کنید. این فرآیند خودکار، ورود هرگونه کد کثیف یا غیراستاندارد را به سرورهای گیت‌هاب یا گیت‌لب کاملاً غیرممکن می‌سازد.

جمع‌بندی و چک‌لیست نهایی برای داشتن کدهایی یکدست و تمیز در تیم

پیکربندی لایترها و فرمترها، سرمایه‌گذاری هوشمندانه‌ای است که ثمرات آن در طول حیات پروژه نمایان می‌شود. استانداردسازی خودکار کدهای پایتون، اصطکاک فنی میان اعضای تیم را به صفر می‌رساند. این فرآیند زمان بررسی کدها (Code Review) را تا حد چشمگیری کاهش می‌دهد و کیفیت خروجی نرم‌افزار را تضمین می‌کند.

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

چک‌لیست طلایی استانداردسازی کد در تیم‌های پایتون

  • پیکربندی واحد: فایل تنظیمات pyproject.toml را در ریشه اصلی ریپازیتوری پروژه بسازید و قوانین Ruff را در آن یک‌بار برای همه اعضا تعریف کنید.
  • هماهنگی ویرایشگرها: افزونه رسمی Ruff را روی سیستم تمام توسعه‌دهندگان (چه در VS Code و چه در PyCharm) نصب و قابلیت اجرای خودکار هنگام ذخیره (Run on Save) را فعال کنید.
  • قرنطینه گیت: ابزار pre-commit را روی گیت محلی پروژه فعال کنید تا از خروج هرگونه کد غیراستاندارد از سیستم برنامه‌نویسان جلوگیری شود.
  • اتصال به CI/CD: دستور ruff check . و ruff format --check . را به عنوان یک گام اجباری در فرآیند تست خودکار سرور (پایپ‌لاین‌های GitHub Actions یا GitLab CI) قرار دهید تا هیچ کدی بدون تایید نهایی ادغام (Merge) نشود.
  • به‌روزرسانی دوره‌ای: نسخه ابزار Ruff و هوک‌های گیت را در فواصل زمانی مشخص به‌روز کنید تا از آخرین قابلیت‌های بهینه‌سازی و کدهای جدید پایتون بهره‌مند شوید.

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

درس قبلی
مدیریت هوشمند خطاها با استثناها
درس بعدی
چک‌لیست بازنویسی کد