استانداردهای کدنویسی

این سند استانداردهای کدنویسی و امضاهای مورد استفاده در پروژه پلنت را مشخص می‌کند. پیروی از این استانداردها، کد تمیز، خوانا و یکنواخت در سراسر پایگاه کد را تضمین می‌کند.

دستورالعمل‌های کلی

• از استانداردهای کدنویسی PSR-12 برای کد PHP پیروی کنید
• از نام‌های متغیر و تابع معنادار استفاده کنید
• توابع را کوچک و متمرکز بر یک مسئولیت واحد نگه دارید
• برای توضیح منطق پیچیده، توضیحات مناسب اضافه کنید
• از تورفتگی یکنواخت استفاده کنید (فاصله، نه تب)
• طول خط را به 120 کاراکتر محدود کنید
• از اشاره‌های نوع (type hints) برای پارامترها و انواع بازگشتی استفاده کنید
• برای تمام قابلیت‌های جدید، تست‌های واحد بنویسید

سازماندهی کد

این پروژه از ساختار استاندارد Laravel با برخی قراردادهای اضافی پیروی می‌کند:

• کنترلرها باید نازک باشند و منطق کسب‌وکار را به سرویس‌ها محول کنند
• برای تعاملات پایگاه داده از مخازن (repositories) استفاده کنید
• منطق اعتبارسنجی را در کلاس‌های Form Request اختصاصی قرار دهید
• از شمارشگرها (enums) برای نمایش مجموعه‌های ثابت مقادیر استفاده کنید
• برای تمام سرویس‌هایی که ممکن است پیاده‌سازی‌های متعدد داشته باشند، رابط (interface) پیاده‌سازی کنید

قراردادهای نام‌گذاری

• کلاس‌ها: PascalCase (مثال: UserService)
• متدها/توابع: camelCase (مثال: getUserById)
• متغیرها: camelCase (مثال: $userCount)
• ثابت‌ها: UPPER_SNAKE_CASE (مثال: MAX_LOGIN_ATTEMPTS)
• جداول پایگاه داده: snake_case، جمع (مثال: user_profiles)
• ستون‌های پایگاه داده: snake_case (مثال: first_name)
• شمارشگرها: PascalCase برای نام شمارشگر، PascalCase برای موارد (مثال: ProductAccessType::Subscriber)

ساختار فایل

• یک کلاس در هر فایل
• نام فایل باید با نام کلاس مطابقت داشته باشد
• فایل‌های مرتبط را در دایرکتوری‌های مناسب گروه‌بندی کنید
• از قرارداد Laravel برای مکان‌های فایل پیروی کنید

بررسی کد

تمام کدها باید قبل از ادغام از یک فرآیند بررسی عبور کنند:

1. هر درخواست ادغام باید توسط مالک کد بررسی شود
2. اگر مالک کد آن را تأیید نکند، توسط CTO بررسی نخواهد شد
3. از قالب درخواست pull ایجاد شده پیروی کنید
4. قبل از درخواست بررسی مجدد، به تمام نظرات بررسی پاسخ دهید

مستندسازی

• تمام متدها و توابع عمومی را مستند کنید
• هنگام اضافه کردن دستورات یا ویژگی‌های جدید، README را به‌روز کنید
• برای قابلیت‌های پیچیده، مثال‌ها را شامل کنید
• هرگونه رفتار غیربدیهی یا موارد حاشیه‌ای را مستند کنید

پیروی از این استانداردها به حفظ یک پایگاه کد با کیفیت بالا کمک می‌کند و همکاری را برای تمام اعضای تیم آسان‌تر می‌سازد.