‫راهنمای دستورالعمل‌های سفارشی گیت‌هاب کوپایلوت در ویژوال استودیو

your-project-root/
├── .github/
│   └── copilot-instructions.md
└── (بقیه فایل‌ها و پوشه‌های پروژه)

# copilot-instructions.md

## استانداردهای کدنویسی (Coding Standards)

### اصول کلی (General Principles)
- **فریم‌ورک هدف:** تمام پروژه‌ها باید .NET 8.0 را هدف قرار دهند. سازگاری با این نسخه الزامی است.
- **زبان:** از زبان C# برای تمام کدها استفاده شود، مگر در موارد خاص.
- **خوانایی:** کدهای واضح و خودتوضیح‌دهنده بنویسید. از نام‌های معنی‌دار برای متغیرها، متدها و کلاس‌ها استفاده کنید.
- **سازگاری:** از قراردادهای نام‌گذاری و قالب‌بندی کد یکسان در کل راهکار (solution) پیروی کنید.
- **کامنت‌گذاری:** کامنت‌های خطی (inline comments) فقط در جایی که برای توضیح منطق پیچیده ضروری است، اضافه شوند.
- **مدیریت خطا (Error Handling):** از مدیریت استثناهای ساختاریافته (structured exception handling) استفاده کنید. از پنهان کردن استثناها (swallowing exceptions) خودداری کرده؛ آن‌ها را ثبت (log) کرده یا مجدداً پرتاب (rethrow) کنید.
- **اصول SOLID:** برای کدهای قابل نگهداری و توسعه‌پذیر، به اصول طراحی SOLID پایبند باشید.
- **تزریق وابستگی (Dependency Injection):** تزریق از طریق سازنده (constructor injection) برای وابستگی‌ها ارجحیت دارد.
- **Async/Await:** از الگوهای برنامه‌نویسی ناهمگام (asynchronous programming patterns) در موارد مناسب، به ویژه برای عملیات وابسته به ورودی/خروجی (I/O-bound operations) استفاده کنید.
- **اعداد جادویی (Magic Numbers):** از اعداد جادویی پرهیز کنید؛ از ثابت‌های نام‌گذاری شده (named constants) یا شمارش‌گرها (enums) استفاده کنید.
- **سازماندهی فایل:** هر فایل باید شامل یک کلاس باشد. فایل‌ها را در پوشه‌های مناسب بر اساس ویژگی (feature) یا لایه (layer) سازماندهی کنید.

### قراردادهای نام‌گذاری (Naming Conventions)
- **کلاس‌ها و واسط‌ها (Interfaces):** PascalCase (مثال: `UserService`، `IUserRepository`)
- **متدها و خصوصیات (Properties):** PascalCase (مثال: `GetUserById`)
- **متغیرها و پارامترها:** camelCase (مثال: `userId`)
- **ثابت‌ها (Constants):** PascalCase (مثال: `DefaultTimeout`)
- **متدهای تست واحد:** از نام‌های توصیفی که سناریو و نتیجه مورد انتظار را نشان می‌دهند، استفاده کنید (مثال: `GetUserById_ReturnsUser_WhenUserExists`)

### سبک کد (Code Style)
- **آکولادها (Braces):** از سبک Allman (آکولادها در خط جدید) استفاده کنید.
- **تورفتگی (Indentation):** از 4 فاصله (spaces) برای هر سطح تورفتگی استفاده کنید.
- **طول خط:** طول خطوط را به 120 کاراکتر محدود کنید.
- **استفاده از عبارت `using`:** عبارت‌های `using` را خارج از فضای نام (namespace) قرار دهید و `using`های استفاده‌نشده را حذف کنید.

---

## استفاده از کوپایلوت (Copilot Usage)

- **هنگام تولید یا اصلاح کد، به این استانداردها پایبند باشید.**
- **الگوها و قراردادهای موجود در راهکار را ترجیح دهید.**
- **کدی تولید کنید که آماده استفاده باشد و به طور یکپارچه در ساختار فعلی جای گیرد.**
- **هرگونه انحراف از این استانداردها را در درخواست‌های پول (pull requests) یا بررسی‌های کد (code reviews) مستند کنید.**

public IActionResult edit(int UserId)
{
    return View();
}

// نمونه کد اصلاح شده توسط کوپایلوت بر اساس دستورالعمل‌ها
public IActionResult Edit(int userId) // "Edit" PascalCase، "userId" camelCase
{
    // ... منطق مربوطه ...
    return View();
}

---

## استانداردهای تست واحد (Unit Test Standards)

### اصول کلی
- **فریم‌ورک تست:** از NUnit و NSubstitute در صورت نیاز برای پروژه استفاده کنید.
- **نام‌گذاری تست:** از نام‌های متد توصیفی استفاده کنید: `MethodName_StateUnderTest_ExpectedBehavior`.
- **ساختار تست:** در تمام تست‌ها از الگوی Arrange-Act-Assert (AAA) پیروی کنید.
- **ایزولاسیون:** هر تست باید مستقل باشد و به نتیجه تست‌های دیگر وابسته نباشد.
- **ماکینگ (Mocking):** برای وابستگی‌های خارجی (مانند APIها) از ماک (mocks) یا فیک (fakes) استفاده کنید تا اطمینان حاصل شود تست‌ها قطعی (deterministic) هستند.