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

چرا فقط دانستن کافی نیست؟

سه دلیل عملی: یک — فراموشی. حتی توسعه‌دهندهٔ حرفه‌ای، در سرعتِ کار، قواعد را از یاد می‌برد. راه‌حل: ابزار خودکار. دو — اختلاف نظر. در تیم، هر کس برداشت خودش را از «کد تمیز» دارد. ابزار، مرجع مشترک است. سه — ورود اعضای جدید. توسعه‌دهندهٔ تازه، بدون ابزار، در یادگیری استاندارد تنها می‌ماند. ابزار، نقش معلم را هم بازی می‌کند. تجربه‌ام: در پروژه‌ای با چهار توسعه‌دهنده، ابزار استاندارد به‌تنهایی، سرعت بازبینی کد را سه برابر کرد. تفاوت بین «قاعدهٔ نوشته‌شده» و «قاعدهٔ اجرا‌شده» همین است.

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

PHP_CodeSniffer با استاندارد وردپرس

ابزار استاندارد بررسی PHP در وردپرس، PHP_CodeSniffer است که با Ruleset رسمی وردپرس (WordPress-Coding-Standards) اجرا می‌شود. این ترکیب، هم توسط تیم وردپرس نگه‌داری می‌شود و هم در هزاران پروژهٔ متن‌باز استفاده می‌شود. این ابزار، کد را برای قواعد زیر بررسی می‌کند: نام‌گذاری، فاصله‌گذاری، تودرتویی، مستندسازی PHPDoc، امنیت (پاک‌سازی ورودی و escape خروجی)، و سازگاری با نسخه‌های مختلف PHP. تجربه‌ام: در پروژه‌ای که برای اولین بار این ابزار را اجرا کردم، بالای ۵۰۰ هشدار در کدی دیدم که «خودم سالم می‌دانستم». همهٔ آن‌ها هم واقعی بودند.

ابزار مکمل برای بررسی سبک‌های دیگر: ESLint برای جاوااسکریپت (با پیکربندی @wordpress/eslint-plugin) و Stylelint برای CSS (با @wordpress/stylelint-config). مجموع این سه، سه لایهٔ اصلی کد وردپرسی را پوشش می‌دهد.

نصب و تنظیم در محیط توسعه

نصب با Composer، استانداردترین روش است:

composer require --dev wp-coding-standards/wpcs
composer require --dev dealerdirect/phpcodesniffer-composer-installer
composer require --dev phpcompatibility/phpcompatibility-wp

پس از نصب، در فایل composer.json اسکریپت‌های بررسی اضافه کنید:

"scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf"
}

و در فایل phpcs.xml.dist در ریشهٔ پروژه، تنظیمات را بنویسید:

<?xml version="1.0"?>
<ruleset name="My Project">
    <description>استاندارد کدنویسی برای پروژهٔ من</description>
    <file>./</file>
    <exclude-pattern>/vendor/*</exclude-pattern>
    <exclude-pattern>/node_modules/*</exclude-pattern>
    <arg name="extensions" value="php"/>
    <arg value="sp"/>
    <rule ref="WordPress"/>
    <rule ref="PHPCompatibilityWP"/>
    <config name="testVersion" value="7.4-"/>
</ruleset>

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

یکپارچه‌سازی با ویرایشگر

برای اینکه در حین کدنویسی، خطاها را ببینید، ابزار را با ویرایشگر یکپارچه کنید. در VS Code، افزونهٔ phpcs این کار را انجام می‌دهد. در PHPStorm، PHPCS به‌صورت داخلی پشتیبانی می‌شود. تجربه‌ام: وقتی توسعه‌دهنده، خطای استاندارد را در همان لحظهٔ نوشتن می‌بیند، در سه هفتهٔ اول، رعایت استاندارد به عادت تبدیل می‌شود. اجرای بعدی ابزار، فقط تأییدیه است.

اجرا در CI (چرخهٔ یکپارچگی مستمر)

اجرای PHPCS در CI، تفاوت بین «استاندارد تشویقی» و «استاندارد اجرایی» است. الگوی استاندارد در GitHub Actions:

name: Coding Standards
on: [push, pull_request]
jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - run: composer install --prefer-dist
      - run: composer lint

با این تنظیم، هر Pull Request که استاندارد را نقض کند، CI رد می‌کند و Merge نمی‌شود. تجربه‌ام: در پروژه‌ای با این تنظیم، در سه ماه، کیفیت کد از سطح «قابل قبول» به «حرفه‌ای» رسید. یک تذکر: برای پروژه‌های موجود که کد قدیمی استاندارد نیستند، به‌جای اجرای CI روی کل کد، فقط روی فایل‌های تغییر‌یافته اجرا کنید — الگو در ادامه می‌آید.

ساخت Ruleset اختصاصی

پروژه‌های جدی، Ruleset اختصاصی دارند که قواعد پیش‌فرض را تنظیم می‌کند. نمونه:

<rule ref="WordPress">
    <exclude name="WordPress.Files.FileName"/>
    <exclude name="Generic.Commenting.DocComment.MissingShort"/>
</rule>
<rule ref="WordPress.WP.I18n">
    <properties>
        <property name="text_domain" type="array">
            <element value="my-plugin"/>
        </property>
    </properties>
</rule>

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

مدیریت خطاهای قابل صرف‌نظر

گاهی یک خط مشخص، باید از بررسی معاف شود. به‌جای غیرفعال کردن قاعده، از کامنت‌های مخصوص PHPCS استفاده کنید:

// phpcs:ignore WordPress.DB.DirectDatabaseQuery
$results = $wpdb->get_results( $query );

// phpcs:disable WordPress.PHP.DiscouragedPHPFunctions
// کدهایی که موقتاً معاف شده‌اند
// phpcs:enable

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

جریان کاری تیمی

پنج قاعدهٔ عملی در تیم: یک — Ruleset یکسان. همه از یک فایل phpcs.xml.dist استفاده کنند. دو — Pre-commit hook. با Husky یا ابزار مشابه، پیش از هر Commit، استاندارد بررسی شود. سه — CI اجباری. Merge بدون عبور از CI، ممنوع. چهار — آموزش دوره‌ای. هر چند هفته، یک جلسهٔ نیم‌ساعته برای مرور قواعد و اشتباهات رایج. پنج — بازبینی کد بشردوستانه. در بازبینی، به کد احترام بگذارید. تیم‌هایی که بازبینی را به مسابقهٔ امتیازدهی تبدیل می‌کنند، به‌سرعت انگیزهٔ خود را از دست می‌دهند. تجربه‌ام: در تیمی که این پنج قاعده را رعایت می‌کرد، کیفیت کد در شش ماه از متوسط به حرفه‌ای رسید.

بازسازی کد قدیمی

پروژه‌های موجود که کد قدیمی استاندارد نیستند، با یک بار اجرای PHPCS، هزاران خطا نشان می‌دهند. راه‌حل سه‌مرحله‌ای: یک — بازسازی تدریجی. به‌جای تلاش برای اصلاح همه‌چیز در یک نشست، هر بار که فایلی را تغییر می‌دهید، استاندارد آن را هم رعایت کنید. دو — حذف تدریجی خطاها. در Ruleset، قواعد را فعال کنید و در فایل baseline، خطاهای فعلی را ثبت کنید. هر Sprint، تعدادی از خطاهای baseline را کاهش دهید. سه — جداسازی کد جدید. کد جدید را از ابتدا استاندارد بنویسید؛ کد قدیمی را در فایل‌های جدا نگه دارید تا با آن‌ها مخلوط نشوند. تجربه‌ام: در پروژه‌ای با ۱۵٬۰۰۰ خط کد استاندارد نشده، با این سه‌گام، در شش ماه، ۸۰٪ خطاها کاهش یافت — بدون توقف توسعه. مسیر مشابهی برای مهاجرت‌های تدریجی در تغییر امن قالب آمده است.

اشتباهات رایج

  • نصب PHPCS بدون تنظیم Ruleset: ابزار با قواعد پیش‌فرض، بخش عمدهٔ قواعد وردپرس را نمی‌بیند.
  • غیرفعال کردن قواعد به‌خاطر سخت‌گیری: یادگیری اولیه سخت است، ولی موقت.
  • معافیت گسترده بدون کامنت: در بازبینی، تبدیل به آشفتگی می‌شود.
  • اجرا نکردن در CI: استاندارد فقط تشویقی می‌شود و در عمل رعایت نمی‌شود.
  • اجرای phpcbf روی کل کد قدیمی: تغییرات انبوه، بازبینی را غیرممکن می‌کند. مرحله‌ای پیش بروید.
  • نادیده‌گرفتن eslint و stylelint: کد وردپرسی شامل JS و CSS هم هست.

جمع‌بندی

پیاده‌سازی استانداردهای کدنویسی وردپرس، سه گام عملی دارد: نصب PHPCS با Ruleset وردپرس، یکپارچه‌سازی با ویرایشگر، و اجرای اجباری در CI. اگر امروز فقط یک کار می‌کنید: فایل phpcs.xml.dist را در پروژهٔ فعلی خود بسازید و PHPCS را اجرا کنید. همان گزارش اول، نقشهٔ بهبود شماست. تجربه‌تان از پیاده‌سازی استاندارد در تیم، در دیدگاه‌ها ارزشمند است. ✍️