اصول کدنویسی تمیز در پروژه‌های وردپرس

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

چرا کد تمیز مهم است؟

سه دلیل که در پروژه‌های واقعی، اهمیت کد تمیز را تثبیت کرده‌اند:

1. هزینه نگهداری: کد تمیز، در آپدیت‌ها نشکن است. کد شلوغ، در هر آپدیت وردپرس یا افزونه‌های بیرونی، نیاز به بازبینی و ترمیم دارد. تجربه من این است که تفاوت هزینه نگهداری کد تمیز و کد شلوغ، در طول یک سال، حدود دو تا سه برابر است.
2. تحویل به تیم: پروژه‌ای که به توسعه‌دهنده دیگری تحویل داده می‌شود، اگر کدش تمیز نباشد، برای نفر بعدی به یک معما تبدیل می‌شود. این هزینه، در بازار ایران که پروژه‌ها اغلب بین فریلنسرها جابه‌جا می‌شوند، بیشتر می‌شود.
3. پایداری در برابر تغییر نیاز: وقتی مشتری می‌خواهد سه سال بعد قابلیت جدیدی اضافه شود، کد تمیز امکان توسعه سریع را می‌دهد. کد شلوغ، هر توسعه جدید را به بازنویسی بخش بزرگی تبدیل می‌کند.

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

کد تمیز، پول نمی‌گیرد اما پول می‌سازد؛ کد شلوغ، پول نمی‌سازد اما هزینه می‌سازد.

اصل اول: نام‌گذاری معنادار

نام‌گذاری، ساده‌ترین و مهم‌ترین بخش کد تمیز است. سه قاعده که در پروژه‌های خودم رعایت می‌کنم:

• پیشوند یکتا برای توابع و کلاس‌ها: در وردپرس فضای نام سراسری است؛ اگر پیشوند نداشته باشید، با افزونه‌های دیگر تعارض می‌کنید. مثال: تابعی با نام myplugin_get_user_data() نه get_user_data(). این یکی از اصلی‌ترین معیارهای استاندارد وردپرس است که در همین راهنما آمده است.
• نام معنادار، نه نام کوتاه: $user_query_result بهتر از $d است. myplugin_calculate_total_price() بهتر از calc(). تفاوت در زمان خواندن کد، در ماه ششم محسوس می‌شود.
• استاندارد سبک نام‌گذاری وردپرس: snake_case برای توابع و متغیرها، Class_Name برای کلاس‌ها، MY_CONSTANT برای ثابت‌ها. این سبک، در تمام اکوسیستم وردپرس رعایت می‌شود و انطباق با آن، کار تیمی را ساده‌تر می‌کند.

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

اصل دوم: توابع کوچک با مسئولیت واحد

هر تابع، باید یک کار مشخص انجام دهد. تابعی که بالای ۵۰ خط است، نشانه‌ای است که باید شکسته شود. سه قاعده در این اصل:

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

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

اصل سوم: جداسازی لایه‌ها

در هر پروژه وردپرسی، سه لایه اصلی وجود دارد که باید در معماری از هم جدا باشند:

1. لایه نمایش (Presentation): شامل فایل‌های template، HTML و CSS. این لایه فقط داده را نمایش می‌دهد و هیچ منطقی ندارد.
2. لایه منطق کسب‌وکار (Business Logic): شامل توابع و کلاس‌هایی که قواعد سایت را پیاده می‌کنند — محاسبه قیمت، اعتبارسنجی، تصمیم‌گیری. این لایه، نه HTML می‌شناسد و نه با دیتابیس مستقیم حرف می‌زند.
3. لایه داده (Data Access): شامل کوئری‌ها و توابعی که با دیتابیس کار می‌کنند. این لایه، نه منطق کسب‌وکار دارد و نه HTML.

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

کد تمیز، یک تصمیم معماری است، نه یک سبک نوشتن. تفاوت بین کد شلوغ و کد تمیز، در تفاوت بین معماری و شتاب است.

اصل چهارم: تکرار نکن (DRY)

اصل DRY (Dont Repeat Yourself) در وردپرس به این معناست: اگر یک قطعه کد را دو جا نوشتید، احتمالاً باید در یک تابع مشترک باشد. سه نشانه که در پروژه‌ها می‌بینم:

• تکرار در نمایش: اگر یک کارت نوشته را در صفحه اصلی، آرشیو، جستجو و مرتبط‌ها نمایش می‌دهید، باید در یک template-parts/content.php باشد، نه در چهار فایل template. الگوی دقیق در ساختار فایل قالب استاندارد آمده است.
• تکرار در منطق: اگر یک محاسبه یا اعتبارسنجی در چند نقطه انجام می‌شود، باید در یک تابع مشترک باشد. تجربه‌ام این است که در ۹۰٪ موارد، تکرار منطق، منبع اصلی باگ‌هایی است که در یک نقطه اصلاح می‌شوند و در دیگری نه.
• تکرار در asset: اگر یک فایل CSS یا JS را در چند جا enqueue می‌کنید، باید یک نقطه ثبت داشته باشد. الگوی enqueue صحیح در افزودن کد سفارشی به وردپرس آمده است.

اصل پنجم: استفاده از هوک‌ها نه ویرایش هسته

در وردپرس، برای اتصال کد شما به هسته، فقط یک راه درست وجود دارد: هوک‌ها. سه اشتباه رایج:

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

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

اصل ششم: امنیت از روز اول

امنیت در کد تمیز، نه چیزی که بعداً اضافه شود، بخشی از کد است. چهار قاعده که در همه پروژه‌ها رعایت می‌کنم:

• Sanitize ورودی: هر داده از کاربر (فرم، URL، AJAX) با sanitize_text_field، absint یا مشابه پاک‌سازی شود. راهنمای کامل در پاک‌سازی داده‌ها در وردپرس و اعتبارسنجی داده‌ها آمده است.
• Escape خروجی: هر داده به HTML با esc_html، esc_attr یا esc_url escape شود. راهنمای کامل در نوشتن PHP امن برای وردپرس.
• Nonce در فرم و AJAX: هر فرم با wp_nonce_field و هر درخواست AJAX با check_ajax_referer محافظت شود. الگوی دقیق در نانس وردپرس و امنیت فرم و پیاده‌سازی نانس در فرم‌های سفارشی.
• Capability check: هر عملیات حساس با current_user_can محافظت شود. راهنما در توابع نقش‌ها و دسترسی‌ها.

کد تمیز و کد امن، در عمل یکسان‌اند؛ چون کد امن، کدی است که از روز اول با اصول امنیتی نوشته شده باشد، نه کدی که بعداً پچ شود. راهنمای کامل امنیت را در امنیت وردپرس برای مبتدیان آورده‌ام.

اصل هفتم: مستندسازی برای آینده

مستندسازی، مهارت پنهانی است که پروژه‌های حرفه‌ای را از آماتور جدا می‌کند. سه سطح مستندسازی:

• PHPDoc در سطح تابع و کلاس: هر تابع مهم باید توضیح داشته باشد که چه کار می‌کند، چه پارامترهایی می‌گیرد و چه چیزی برمی‌گرداند. الگوی استاندارد PHPDoc در استانداردهای کدنویسی وردپرس.
• کامنت درون‌خطی: برای توضیح «چرا»، نه «چه». کد خوب، خودش می‌گوید «چه»؛ کامنت باید بگوید «چرا» این تصمیم گرفته شده. مثال: به جای // جمع دو عدد، بنویسید // با ضریب مالیات، چون در ایران نرخ ارزش افزوده دارد.
• مستندسازی سطح پروژه: فایل README یا CHANGELOG در پروژه، که قابلیت‌ها، نسخه‌ها و تصمیم‌های معماری را فهرست می‌کند. تجربه من این است که این سند، در انتقال پروژه به توسعه‌دهنده دیگر، ساعت‌ها وقت صرفه‌جویی می‌کند.

جدول چک‌لیست اصول

جمع‌بندی هفت اصل کد تمیز در وردپرس:

ابزارهای اجرای اصول

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

• PHP_CodeSniffer با استاندارد وردپرس: ابزار رسمی بررسی کیفیت کد. مسیر پیاده‌سازی در استفاده از استانداردها در پروژه‌ها.
• PHP Mess Detector: ابزاری که کدهای پیچیده، توابع طولانی و متغیرهای بی‌استفاده را کشف می‌کند. مکمل PHP_CodeSniffer است.
• Git و Code Review: در پروژه‌های تیمی، بازبینی کد قبل از Merge، یکی از مؤثرترین راه‌های ترویج کد تمیز است. الگوی Git در گیت در وردپرس آمده است.

تجربه‌ام این است که این سه ابزار، در کنار هم، در سه هفته اول، سطح کیفیت کد را به‌طور محسوس بالا می‌برند. اگر نمی‌دانید از کجا شروع کنید، با PHP_CodeSniffer شروع کنید؛ در ۹۰٪ پروژه‌ها، این ابزار چند خطای امنیتی و ساختاری کشف می‌کند.

اشتباهات رایج در کدنویسی وردپرس

در اشتباهات رایج توسعه وردپرس فهرست کامل را نوشته‌ام؛ اما چهار مورد که در پروژه‌های مختلف بیشتر می‌بینم:

• ریختن همه‌چیز در functions.php: این فایل در پروژه‌های بزرگ، به فایلی غیرقابل‌نگهداری تبدیل می‌شود. مسیر تقسیم در ساختار فایل قالب استاندارد.
• نصب افزونه برای هر قابلیت کوچک: هر افزونه، یک نقطه شکست و یک مالیات نگهداری است. تفکر «کمتر ولی درست» را در افزونه‌های ضروری وردپرس و چند افزونه نصب کنیم آورده‌ام.
• نبود مستندسازی: کدی که سه سال بعد خودتان هم نمی‌فهمید، هزینه نگهداری دارد. الگوی مستندسازی در همین مقاله و در استانداردها آمده است.
• کپی/پیست بدون فهم: بزرگ‌ترین منبع بدهی فنی است. کدی که از سایت دیگر کپی می‌کنید، ممکن است در محیط شما رفتار متفاوتی داشته باشد.

دید مهندسی

از منظر مهندسی، اصول کد تمیز در وردپرس یک تصمیم معماری پیوسته است، نه یک بار تنظیم و فراموش. سه لایه را در پروژه‌های حرفه‌ای همیشه مرور می‌کنم. لایه اول، Consistency در سطح پروژه: همان‌طور که در سبک نام‌گذاری یک قاعده را انتخاب می‌کنید، در سبک خطاگیری، سبک مستندسازی و سبک تست هم باید یک قاعده مشخص داشته باشید. پروژه‌ای که در یک فایل procedural و در فایل دیگر OOP است، هزینه نگهداری دوبرابر دارد. تفصیل این یکدستی را در ساختاربندی پروژه وردپرس آورده‌ام. لایه دوم، تست‌پذیری: کد تمیز باید قابل تست باشد. اگر تابعی دارید که منطق پیچیده‌ای دارد، باید بتوانید آن را با PHPUnit تست کنید. اگر تابع شما به وردپرس و دیتابیس متصل است، باید آن را به لایه‌های کوچک‌تر تقسیم کنید تا تست‌پذیری حفظ شود. مسیر تست را در تست و دیباگ پروژه‌های وردپرس آورده‌ام. لایه سوم، انعطاف در برابر تغییر: کد تمیز، تغییر را ساده می‌کند. اگر مشتری بخواهد فردا قابلیتی که امروز وجود ندارد اضافه شود، کد تمیز اجازه می‌دهد که در یک نقطه اضافه شود. کد شلوغ، نیازمند بازنویسی بخشی از پروژه است. این تفاوت، در پروژه‌های سه‌ساله، معیار اصلی بین کد قابل نگهداری و بدهی فنی است.

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

جمع‌بندی

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

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