قراردادهای کدنویسی
فهرست مطالب
قراردادهای نامگذاری
- قوانین کلی
- پیاچپی
- جاوااسکریپت/تایپاسکریپت
- پایگاه داده
قوانین کلی نامگذاری
- از نامهای توصیفی که به وضوح هدف را بیان میکنند استفاده کنید
- از اختصارات به جز موارد پذیرفته شده عمومی (مانند ID، HTTP) خودداری کنید
- نامها را مختصر اما بدون قربانی کردن وضوح نگه دارید
- با الگوهای موجود در کد پایه سازگار باشید
نکته
اگر بیش از یک دقیقه برای فکر کردن به یک نام وقت صرف میکنید، احتمالاً بیش از حد پیچیده است. بازنویسی یا تجزیه کامپوننت را در نظر بگیرید.
قراردادهای نامگذاری PHP
- کلاسها: PascalCase (مثال:
UserRepository،PaymentService) - متدها: camelCase (مثال:
getUserById()،processPayment()) - ویژگیها: camelCase (مثال:
$userName،$paymentAmount) - ثابتها: UPPER_SNAKE_CASE (مثال:
MAX_LOGIN_ATTEMPTS،API_VERSION) - فضای نامها: PascalCase (مثال:
App\Services\Payment)
مدلها
- اسم مفرد (مثال:
User، نهUsers) - بدون پیشوند یا پسوند (مثال:
Product، نهProductModel)
کنترلرها
- با پسوند
Controller(مثال:UserController) - کنترلرهای منبع باید از اسامی جمع استفاده کنند (مثال:
ProductsController)
ریپوزیتوریها
- با پسوند
Repository(مثال:UserRepository)
قراردادهای نامگذاری جاوااسکریپت/تایپاسکریپت
- متغیرها: camelCase (مثال:
userName،paymentAmount) - توابع: camelCase (مثال:
getUserData()،calculateTotal()) - کلاسها: PascalCase (مثال:
UserService،PaymentProcessor) - ثابتها: UPPER_SNAKE_CASE (مثال:
MAX_RETRY_COUNT،DEFAULT_TIMEOUT) - ویژگیهای خصوصی: با پیشوند زیرخط (مثال:
_privateData) - فایلهای کامپوننت: PascalCase (مثال:
UserProfile.vue،PaymentForm.jsx) - فایلهای غیرکامپوننت: camelCase (مثال:
apiService.js،formUtils.ts)
قراردادهای نامگذاری پایگاه داده
- جداول: snake_case، جمع (مثال:
users،order_items) - ستونها: snake_case (مثال:
first_name،created_at) - کلیدهای اصلی:
id(مفرد) - کلیدهای خارجی: نام جدول مفرد +
_id(مثال:user_id،product_id) - جداول واسط: نام جداول مفرد به ترتیب الفبا (مثال:
product_user) - ایندکسها:
idx_[جدول]_[ستون(ها)](مثال:idx_users_email) - محدودیتهای یکتا:
unq_[جدول]_[ستون(ها)](مثال:unq_users_email)
سازماندهی فایلها
ساختار دایرکتوری
ساختار دایرکتوری مورد توافق ما به این صورت است:
app/
├── Console/ # دستورات کنسول
├── Contracts/ # اینترفیسها
├── Events/ # کلاسهای رویداد
├── Exceptions/ # استثناهای سفارشی
├── Http/
│ ├── Controllers/ # کنترلرهای گروهبندی شده بر اساس دامنه
│ ├── Middleware/ # میدلورهای HTTP
│ └── Requests/ # درخواستهای فرم
├── Jobs/ # کارهای صف
├── Listeners/ # شنوندههای رویداد
├── Models/ # مدلهای Eloquent
├── Policies/ # خطمشیهای احراز هویت
├── Providers/ # ارائهدهندگان سرویس
├── Repositories/ # پیادهسازیهای الگوی ریپوزیتوری
├── Services/ # سرویسهای منطق کسبوکار
└── Utilities/ # کلاسها و توابع کمکی
یادداشت
قبل از ایجاد دایرکتوریهای جدید، باید با تیم هماهنگ شود تا یکپارچگی حفظ شود.
قوانین قرارگیری فایلها
- هر کلاس باید در فایل مخصوص به خود باشد
- نام فایل باید دقیقاً با نام کلاس مطابقت داشته باشد
- فایلهای مرتبط باید در زیرشاخههای دامنه/ویژگی گروهبندی شوند
- ساختار فایلهای تست باید منعکسکننده ساختار کد برنامه باشد
سبک کدنویسی
تیم ما از سبک کدنویسی PSR-12 برای PHP با برخی توافقات اضافی پیروی میکند:
- حداکثر طول خط: 100 کاراکتر
- تورفتگی با استفاده از 4 فاصله (نه تب)
- همیشه از آکولاد برای ساختارهای کنترلی استفاده کنید، حتی برای دستورات تک خطی
- در آرایههای چندخطی، ویرگول انتهایی اضافه کنید
- ترتیب عناصر کلاس: ثابتها، ویژگیها، سازنده، متدهای عمومی، متدهای حفاظتشده، متدهای خصوصی
استانداردهای مستندسازی
توضیحات کد
- «چرایی» را مستند کنید نه «چیستی» (کد باید به خودی خود گویا باشد)
- توضیحات PHPDoc/JSDoc را برای تمام متدها و کلاسهای عمومی اضافه کنید
- مستندسازی نوع پارامترها و نوع بازگشتی را شامل شوید
- استثناهای احتمالی را مستند کنید
- توضیحات را با تغییرات کد بهروز نگه دارید
فایلهای README
هر کامپوننت اصلی باید یک فایل README.md داشته باشد که شامل موارد زیر است:
- هدف کامپوننت
- دستورالعملهای نصب/راهاندازی
- مثالهای استفاده
- وابستگیها
- مشکلات رایج و راهحلها
استثناهای مورد توافق
در حالی که ما به دنبال رعایت یکنواخت این قراردادها هستیم، در موارد زیر استثنا قائل شدهایم:
- کدهای قدیمی ممکن است تا زمان بازنویسی از این قراردادها پیروی نکنند
- یکپارچهسازی با سرویسهای شخص ثالث ممکن است نیاز به انحراف از قراردادهای نامگذاری داشته باشد
- کدهای حیاتی از نظر عملکرد ممکن است بهینهسازی را بر رعایت دقیق قراردادها ترجیح دهند
اجرا
این قراردادها از طریق موارد زیر اجرا میشوند:
- بازبینی کد
- ابزارهای خودکار بررسی کد
- جلسات برنامهنویسی زوجی
- بحثهای منظم در مورد کیفیت کد