ساختار استاندارد کدنویسی در وردپرس
راهنمای ساختار استاندارد کدنویسی وردپرس؛ از نام‌گذاری و فایلبندی تا مستندسازی، ابزارها و اجرا در پروژه‌های واقعی.
در سال‌ها کار روی پروژه‌های وردپرسی، از افزونه‌های کوچک تا پلتفرم‌های سازمانی، یک الگو را بارها دیده‌ام: کدی که در ماه اول «کار می‌کند» اما ساختار استاندارد ندارد، در ماه سوم به یک بدهی فنی تبدیل می‌شود که هر تغییر کوچک، ساعت‌ها وقت می‌برد. در مقابل، پروژه‌هایی که از روز اول بر پایه ساختار استاندارد کدنویسی وردپرس نوشته شده‌اند، پس از دو سال همچنان قابل نگهداری و قابل تحویل به توسعه‌دهنده دیگر هستند. تفاوت، در دانش نیست؛ در انطباق با یک ساختار مشخص است که جامعه وردپرس، طی سال‌ها روی آن توافق کرده. این مقاله، همان ساختار استاندارد را از پایه تا کاربرد در پروژه‌های واقعی باز می‌کند. اگر با مفاهیم پایه آشنا نیستید، پیش از ادامه توسعه وردپرس چیست، شروع اصولی کدنویسی وردپرس و استانداردهای کدنویسی وردپرس را بخوانید.
ساختار استاندارد دقیقاً چه معنایی دارد؟
وقتی از «ساختار استاندارد کدنویسی در وردپرس» حرف می‌زنیم، منظور مجموعه‌ای از قواعد مشخص است که در سه سطح عمل می‌کند:
- سطح نام‌گذاری: قواعدی که مشخص می‌کند چه نامی برای متغیر، تابع، کلاس و ثابت مناسب است.
- سطح ساختار فایل: قواعدی که مشخص می‌کند کد شما در چه پوشه‌ها و فایل‌هایی زندگی می‌کند و مرز بین لایه‌ها کجاست.
- سطح سبک نوشتن: قواعدی که مشخص می‌کند تودرتویی، فاصله‌ها، کامنت‌ها و مستندسازی چگونه باشند.
این سه سطح، پایه مستندات رسمی وردپرس هستند و در ابزارهایی مثل PHP_CodeSniffer با استاندارد وردپرس اجرا می‌شوند. تفاوت بین کد استاندارد و غیراستاندارد، در عملکرد روز اول نیست — هر دو کار می‌کنند؛ تفاوت در روز ششماهه است، وقتی آپدیت می‌آید یا توسعه‌دهنده جدید به تیم اضافه می‌شود. اگر می‌خواهید تفاوت را در عمق ببینید، پیاده‌سازی استانداردها در پروژه‌ها را مرور کنید.
استاندارد کدنویسی، مالیات نیست؛ بیمه‌نامه است. روز اول هزینه دارد، سال دوم نجات می‌دهد.
لایه اول: استاندارد نام‌گذاری
نام‌گذاری، ساده‌ترین لایه استاندارد است اما بیشترین اثر را در خوانایی کد دارد. چهار قاعده اصلی:
- پیشوند یکتا: تمام توابع، کلاس‌ها و ثابت‌ها باید پیشوند اختصاصی داشته باشند. در فضای نام سراسری PHP، این پیشوند، تضمین‌کننده عدم تعارض با افزونه‌ها و قالب‌های دیگر است. مثال:
myplugin_get_user_data()نهget_user_data(). - سبک snake_case برای توابع و متغیرها:
myplugin_calculate_total()نهmyPluginCalculateTotal()و نهmyPlugin_calculateTotal(). این سبک، استاندارد وردپرس است. - سبک Class_Name برای کلاس‌ها:
My_Plugin_LoaderنهMyPluginLoader. این سبک در تمام اکوسیستم وردپرس رعایت می‌شود. - سبک MY_CONSTANT برای ثابت‌ها:
MY_PLUGIN_VERSIONنهmyPluginVersion. همه حروف بزرگ با underscore.
تجربه من این است که در پروژه‌ای که نام‌گذاری درست باشد، بازبینی کد چند برابر سریع‌تر انجام می‌شود. حتی اگر امروز خودتان تنها توسعه‌دهنده هستید، رعایت این سبک، کار شما را در ماه ششم با خودتان هم آسان‌تر می‌کند. تفصیل کامل این قواعد در استانداردهای کدنویسی وردپرس آمده است.
لایه دوم: ساختار فایل‌ها و پوشه‌ها
ساختار فایل‌ها، تفاوت بین پروژه‌ای است که به سادگی توسعه می‌یابد و پروژه‌ای که در ماه سوم تبدیل به یک آشفتگی می‌شود. ساختار استاندارد برای افزونه و قالب، قواعد مشخصی دارد که در ساختار فایل‌های افزونه استاندارد و ساختار فایل‌های قالب استاندارد آورده‌ام. خلاصه قواعد:
- فایل اصلی در ریشه: افزونه با فایل
my-plugin.phpو قالب با فایلstyle.cssوfunctions.phpدر ریشه شروع می‌شود. - پوشه includes/ برای منطق: تمام کلاس‌ها و توابع در این پوشه قرار می‌گیرند. مرزهای مشخص: کلاس‌های عمومی، کلاس‌های ادمین و کلاس‌های front هرکدام در فایل جداگانه.
- پوشه admin/ برای کد پیشخوان: منطق مربوط به صفحات تنظیمات، متاباکس و asset پیشخوان در این پوشه زندگی می‌کند. این جداسازی، فشار بار را در front-end کاهش می‌دهد.
- پوشه public/ برای کد front: کد مربوط به نمایش front، در این پوشه. اگر قالب سایت شما با افزونه شما کار دارد، کد template هم اینجا قرار می‌گیرد.
- پوشه assets/ برای CSS، JS و تصاویر: فایل‌های استاتیک در این پوشه با ساختار
assets/css/،assets/js/،assets/images/. - پوشه languages/ برای فایل .pot: فایل ترجمه پایه در این پوشه قرار می‌گیرد.
- فایل uninstall.php برای پاک‌سازی: اگر افزونه شما در حذف باید جدول یا تنظیمات را پاک کند، این فایل وارد میدان می‌شود.
تجربه‌ام این است که در پروژه‌هایی که این ساختار رعایت شود، حتی اگر تیم عوض شود، نفر بعدی در نیم ساعت اول می‌فهمد که کد کجا زندگی می‌کند.
لایه سوم: سبک نوشتن و تودرتویی
سبک نوشتن، یک ظرافت ظاهری نیست؛ ابزاری برای خوانایی و پیشگیری از خطاست. قواعد اصلی استاندارد وردپرس:
- تودرتویی با tab نه space: استاندارد وردپرس از tab استفاده می‌کند. دلیلش، سازگاری با ویرایشگرهای مختلف و صرفه‌جویی در فضای نمایش است.
- آکولاد باز در همان خط:
function my_function() {نهfunction my_function() {. این سبک، در تمام استاندارد وردپرس رعایت می‌شود. - yoda conditions در مقایسه‌ها:
if ( true === $var )نهif ( $var === true ). دلیلش، جلوگیری از اشتباه رایج$var = true(تخصیص به جای مقایسه) است. - فاصله‌گذاری درست: بعد از کاما در پارامترها، یک فاصله؛ داخل پرانتز تابع، بدون فاصله اضافی.
- حذف تگ بسته PHP در انتهای فایل: در فایل‌های PHP خالص، تگ
?>انتهای فایل را حذف کنید؛ چون فاصله‌های بعد از آن می‌تواند خطای headers already sent ایجاد کند. - یک خط خالی بین توابع: این ظرافت کوچک، خوانایی کد را محسوس افزایش می‌دهد.
این قواعد، در ابزار PHP_CodeSniffer به‌صورت خودکار بررسی می‌شوند. مسیر پیاده‌سازی این ابزار را در استفاده از استانداردها در پروژه‌ها آورده‌ام.
سبک نوشتن، تفاوت بین کدی است که سه ماه بعد خودتان هم می‌فهمید، با کدی که در همان ماه اول، خواندنش وقت می‌گیرد.
لایه چهارم: مستندسازی و PHPDoc
مستندسازی، مهارت پنهانی است که پروژه‌های حرفه‌ای را از آماتور جدا می‌کند. سه سطح استاندارد مستندسازی:
- PHPDoc در سطح فایل: در ابتدای هر فایل PHP، یک بلوک کامنت قرار می‌گیرد که هدف فایل، وابستگی‌ها و توضیح کوتاه آن را می‌گوید. الگوی استاندارد وردپرس این ساختار را رعایت می‌کند.
- PHPDoc در سطح تابع و کلاس: هر تابع مهم، باید در بالای خود یک بلوک PHPDoc داشته باشد که هدف، پارامترها، مقدار بازگشتی و استثناها را توضیح دهد. مثال:
/** * محاسبه قیمت نهایی با احتساب مالیات * * @param float $base_price قیمت پایه * @param float $tax_rate نرخ مالیات * @return float قیمت نهایی */ - کامنت درون‌خطی برای «چرا»: کامنت باید توضیح دهد که چرا یک تصمیم گرفته شده، نه اینکه چه اتفاقی می‌افتد. کد خوب، خودش «چه» را می‌گوید. مثال: به جای
// جمع دو عدد، بنویسید// ضریب 1.09 برای نرخ ارزش افزوده، چون مشتری داخلی است.
تجربه‌ام این است که پروژه‌هایی که PHPDoc درست دارند، در انتقال به توسعه‌دهنده دیگر، هفته‌ها وقت صرفه‌جویی می‌کنند. اگر با استاندارد کامل PHPDoc در وردپرس آشنا نیستید، مستندات رسمی وردپرس مرجع خوبی است؛ خلاصه‌اش در استانداردهای کدنویسی وردپرس آمده است.
لایه پنجم: enqueue و مدیریت asset
روش استاندارد لود CSS و JS در وردپرس، استفاده از wp_enqueue_style و wp_enqueue_script است، نه تگ مستقیم. سه قاعده اصلی:
- enqueue در هوک درست: در front از هوک
wp_enqueue_scriptsو در پیشخوان ازadmin_enqueue_scripts. تفصیل کامل هوک‌ها در هوک‌های وردپرس چیست. - وابستگی‌ها را درست تعریف کنید: اگر اسکریپت شما به jQuery وابسته است، این وابستگی را در پارامتر سوم
wp_enqueue_scriptذکر کنید. این کار، ترتیب لود درست را تضمین می‌کند. - بارگذاری شرطی: فقط در صفحاتی که لازم است، فایل لود کنید. اگر یک CSS فقط در صفحه دوره لازم است، آن را در بقیه صفحات لود نکنید. این تکنیک، از بزرگ‌ترین عوامل بهبود سرعت است. تفصیل این موضوع را در افزایش سرعت سایت وردپرسی آورده‌ام.
یک نکته استانداردی که در پروژه‌های وردپرسی زیاد دیده‌ام و اشتباه است: enqueue دستی با تگ <link> و <script> در header یا footer. این کار باعث می‌شود که کش افزونه‌ها نتوانند فایل‌ها را بهینه کنند و در ترتیب لود، مشکل ایجاد شود. الگوی درست در افزودن کد سفارشی به وردپرس آمده است.
لایه ششم: ترجمه‌پذیری
حتی اگر پروژه اختصاصی است و امروز فقط در یک زبان استفاده می‌شود، استاندارد ترجمه‌پذیری، از روز اول باید رعایت شود. سه قاعده اصلی:
- استفاده از توابع ترجمه: تمام رشته‌های متنی با
__()،_e()،esc_html__()یا مشابه نوشته شوند. مثال: به جایecho 'تنظیمات ذخیره شد';ازecho esc_html__( 'تنظیمات ذخیره شد', 'my-plugin' );. - Text Domain یکتا: در هدر افزونه، پارامتر
Text Domainتعریف می‌شود و همان در تمام توابع ترجمه استفاده می‌شود. نه چندین text domain، نه نام متفاوت در فایل‌های مختلف. - فایل .pot در پوشه languages: فایل ترجمه پایه با ابزارهایی مثل WP-CLI یا Poedit ساخته می‌شود. بارگذاری آن با
load_plugin_textdomainدر هوکinitانجام می‌شود.
تفصیل کامل ترجمه‌پذیری را در آماده‌سازی قالب برای فارسی آورده‌ام؛ اصول برای افزونه هم صادق است. اگر با سایت چندزبانه کار می‌کنید، مسیر راه‌اندازی در چگونه از وردپرس چندزبانه استفاده کنیم آمده است.
لایه هفتم: استاندارد امنیتی
امنیت، بخشی از ساختار استاندارد کد است، نه چیزی که بعداً اضافه شود. چهار قاعده اصلی که در استاندارد وردپرس رعایت می‌شوند:
- Sanitize ورودی: هر داده از کاربر با
sanitize_text_field،absintیا مشابه پاک‌سازی شود. راهنمای کامل در پاک‌سازی داده‌ها در وردپرس و اعتبارسنجی داده‌ها. - Escape خروجی: هر داده به HTML با
esc_html،esc_attrیاesc_urlescape شود. راهنمای کامل در نوشتن PHP امن برای وردپرس. - Nonce در فرم و AJAX: هر فرم با
wp_nonce_fieldو هر درخواست AJAX باcheck_ajax_refererمحافظت شود. الگوی دقیق در نانس وردپرس و امنیت فرم. - Capability check: هر عملیات حساس با
current_user_canمحافظت شود. راهنما در توابع نقش‌ها و دسترسی‌ها.
در استاندارد وردپرس، این چهار قاعده، در PHP_CodeSniffer با عنوان استاندارد WordPress.Security بررسی می‌شوند. اگر گزارش این ابزار در این بخش‌ها خطا نشان دهد، باید در همان هفته اول ترمیم شوند. راهنمای کامل امنیت را در امنیت وردپرس برای مبتدیان آورده‌ام.
استاندارد PHP، JS و CSS در وردپرس
هر زبان، در اکوسیستم وردپرس، استاندارد سبک مخصوص خودش را دارد:
| زبان | استاندارد اصلی | نکته کلیدی |
|---|---|---|
| PHP | WordPress PHP Coding Standards | snake_case، tab، yoda condition |
| JavaScript | WordPress JavaScript Coding Standards | camelCase، ES6 در پروژه‌های جدید |
| CSS | WordPress CSS Coding Standards | خط تیره، tab، ترتیب الفبایی propertyها |
| HTML | WordPress HTML Standards | تگ معنایی، دسترس‌پذیری |
تجربه‌ام این است که رعایت این استانداردها، در پروژه‌های تیمی، تفاوت بین بازبینی سریع و بازبینی کند را می‌سازد. مسیر ابزارهای اجرایی این استانداردها در بخش بعد می‌آید.
جدول چک‌لیست ساختار
جمع‌بندی هفت لایه ساختار استاندارد کدنویسی وردپرس:
| لایه | سوال کلیدی | نشانه نقض |
|---|---|---|
| نام‌گذاری | پیشوند و سبک درست؟ | تابع بدون پیشوند، سبک اشتباه |
| ساختار فایل | پوشه‌بندی درست است؟ | همه‌چیز در یک فایل |
| سبک نوشتن | tab، yoda، فاصله‌گذاری درست؟ | space، acolade در خط جدا |
| مستندسازی | PHPDoc دارد؟ | کد بدون هیچ کامنت |
| enqueue asset | با wp_enqueue یا مستقیم؟ | تگ link و script مستقیم |
| ترجمه‌پذیری | توابع ترجمه استفاده شده؟ | رشته‌های hardcoded |
| امنیت | sanitize و escape رعایت شده؟ | خروجی بدون escape |
ابزارهای اجرای ساختار
برای اینکه ساختار استاندارد، به عادت روزمره تبدیل شود، سه ابزار در پروژه‌های خودم استفاده می‌کنم:
- PHP_CodeSniffer با استاندارد WordPress: ابزار رسمی بررسی کیفیت کد. مسیر پیاده‌سازی در استفاده از استانداردها در پروژه‌ها.
- ESLint با پیکربندی WordPress: معادل PHP_CodeSniffer برای JavaScript. در پروژه‌های مدرن که کد JS زیادی دارند، ضروری است.
- Stylelint با پیکربندی WordPress: معادل برای CSS. در پروژه‌های قالب و چایلد تم، اثر محسوسی روی یکدستی کد دارد.
تجربه‌ام این است که این سه ابزار در کنار هم، در سه هفته اول، سطح کیفیت کد را محسوس بالا می‌برند. اگر می‌خواهید این استانداردها را به‌صورت خودکار در CI اجرا کنید، مسیر در CI/CD در وردپرس آمده است.
اشتباهات رایج در ساختار کد
در اشتباهات رایج توسعه وردپرس فهرست کامل را نوشته‌ام؛ اما چهار مورد که در ساختار کد بیشتر می‌بینم:
- نبود پیشوند یکتا: در پروژه‌های تیمی، بزرگ‌ترین منبع تعارض. تابعی با نام
get_user_data()در افزونه شما، با افزونه‌های دیگر به تعارض می‌خورد. راهنمای رفع تعارض در شناسایی افزونه مشکل‌ساز. - ریختن همه‌چیز در functions.php: در ماه دوم، این فایل به فایلی غیرقابل‌نگهداری تبدیل می‌شود. مسیر تقسیم در ساختار فایل قالب استاندارد.
- نبود sanitize در register_setting: اگر sanitize_callback تعریف نشود، داده ورودی بدون فیلتر ذخیره می‌شود و خطر امنیتی جدی ایجاد می‌شود. راهنمای کامل در ساخت صفحه تنظیمات اختصاصی.
- ویرایش مستقیم هسته یا قالب والد: این اشتباه، در ماه سوم خودش را در آپدیت نشان می‌دهد. مسیر درست، استفاده از چایلد تم و افزونه اختصاصی است. تفصیل بیشتر در ساختار هسته وردپرس.
یک اشتباه کم‌تکرار اما گران‌قیمت: نادیده‌گرفتن ترتیب لود asset. اگر فایل CSS شما بعد از فایل JS لود شود یا برعکس، حتی اگر هر دو درست نوشته شده باشند، نتیجه نهایی اشتباه می‌شود. این نوع اشتباهات، با ابزار PHP_CodeSniffer قابل کشف هستند اما در بازبینی چشمی دیده نمی‌شوند.
دید مهندسی
از منظر مهندسی، ساختار استاندارد کدنویسی یک تصمیم معماری پیوسته است، نه یک بار تنظیم و فراموش. سه لایه را در پروژه‌های حرفه‌ای همیشه مرور می‌کنم. لایه اول، Consistency در سطح پروژه: همان‌طور که در سبک نام‌گذاری یک قاعده را انتخاب می‌کنید، در سبک خطاگیری، سبک مستندسازی و سبک تست هم باید یک قاعده مشخص داشته باشید. پروژه‌ای که در یک فایل procedural و در فایل دیگر OOP است، هزینه نگهداری دوبرابر دارد. تفصیل این یکدستی را در ساختاربندی پروژه وردپرس و اصول کدنویسی تمیز آورده‌ام. لایه دوم، جداسازی منطق از نمایش و داده: ساختار استاندارد، بدون جداسازی لایه‌ها ناقص است. منطق کسب‌وکار در افزونه، ظاهر در قالب، و داده در هسته وردپرس. این جداسازی، در روز تغییر قالب یا بازنویسی، هزینه نگهداری را کاهش می‌دهد. الگوی دقیق در ساختار فایل افزونه استاندارد و ساختار فایل قالب استاندارد آمده است. لایه سوم، تست‌پذیری و پایش کیفیت: ساختار استاندارد، فقط خوانایی نیست؛ تست‌پذیری هم هست. اگر تابعی پیچیده دارید، باید بتوانید آن را با PHPUnit تست کنید. اگر تابع به وردپرس و دیتابیس متصل است، باید به لایه‌های کوچک‌تر تقسیم شود. مسیر تست را در تست و دیباگ پروژه‌های وردپرس آورده‌ام.
یک نکته تکمیلی برای تیم‌های فنی: در پروژه‌های بزرگ، ساختار استاندارد باید در سطح قواعد تیمی مستندسازی و در چرخه بازبینی کد اجرا شود. تجربه من این است که در تیمی که این هفت لایه را در بازبینی کد اجرا می‌کند، در شش ماه، سطح کیفیت کد به‌طور محسوس بالا می‌رود. اگر می‌خواهید ساختار را از روز اول در CI اجرا کنید، مسیر کامل در استفاده از استانداردها در پروژه‌ها و CI/CD در وردپرس آمده است. تفاوت بین پروژه‌ای که ساختار استاندارد دارد و پروژه‌ای که ندارد، در ماه ششم، ساعت‌ها کار است — نه در ظاهر.
جمع‌بندی
ساختار استاندارد کدنویسی وردپرس، در هفت لایه خلاصه می‌شود: نام‌گذاری، ساختار فایل، سبک نوشتن، مستندسازی، enqueue asset، ترجمه‌پذیری، و امنیت. سه اصل در پایان تاکید می‌کنم: اول، از روز اول این ساختار را رعایت کنید، نه بعداً. دوم، ابزارها را در جریان کاری خود بگنجانید، نه به‌عنوان بازبینی یک‌بار در سال. سوم، ساختار استاندارد، تفاوت بین پروژه‌ای است که سه سال عمر می‌کند و پروژه‌ای که در ماه ششم به بازنویسی می‌رسد.
اگر همین امروز در حال کار روی یک پروژه وردپرسی هستید، پیشنهاد عملی من سه گام است: ابتدا فهرست هفت لایه بالا را در یک برگه بنویسید و روی کد فعلی خود اعمال کنید؛ اگر از روز اول رعایت نکرده‌اید، به‌جای بازنویسی کامل، هر بار که یک فایل را تغییر می‌دهید، همان فایل را با این ساختار هم‌راستا کنید؛ و در تیم، ابزار PHP_CodeSniffer و بازبینی کد را در جریان کاری خود بگنجانید. اگر در هر مرحله‌ای گیر کردید یا تجربه‌ای از رعایت یا نقض ساختار استاندارد دارید، در دیدگاه‌ها بنویسید. تجربه شما از یک پروژه با ساختار استاندارد یا یک پروژه با بدهی فنی، برای توسعه‌دهنده بعدی که در همین نقطه ایستاده، ارزشمندترین راهنماست. 📐
نویسنده در وردپرس کار.