Refactor

---
name: refactor
description: ری‌فاکتور نظام‌مند کد بر پایه روش‌شناسی مارتین فاولر. زمانی استفاده کنید که کاربران درخواست ری‌فاکتور کد، بهبود ساختار کد، کاهش بدهی فنی، پاک‌سازی کد قدیمی، حذف بوی کد یا بهبود قابلیت نگهداری کد را دارند. این مهارت رویکردی مرحله‌ای با پژوهش، برنامه‌ریزی و پیاده‌سازی ایمن و تدریجی را راهنمایی می‌کند.
---

# مهارت ری‌فاکتور کد

رویکردی نظام‌مند برای ری‌فاکتور کد بر پایه کتاب *Refactoring: Improving the Design of Existing Code* (ویرایش دوم) نوشته مارتین فاولر. این مهارت بر تغییرات ایمن و تدریجی که با تست پشتیبانی می‌شوند تأکید دارد.

> «ری‌فاکتور فرایند تغییر یک سامانه نرم‌افزاری به‌گونه‌ای است که رفتار بیرونی کد را تغییر نمی‌دهد و در عین حال ساختار درونی آن را بهبود می‌بخشد.» — مارتین فاولر

## اصول بنیادین

1. **حفظ رفتار**: رفتار بیرونی باید بدون تغییر بماند
2. **گام‌های کوچک**: تغییرات ریز و آزمون‌پذیر ایجاد کنید
3. **تست‌محور**: تست‌ها تور ایمنی هستند
4. **پیوسته**: ری‌فاکتور فرایندی مستمر است، نه رویدادی یک‌باره
5. **همکارانه**: تأیید کاربر در هر فاز الزامی است

## نمای کلی جریان کار

```
فاز ۱: پژوهش و تحلیل
    ↓
فاز ۲: ارزیابی پوشش تست
    ↓
فاز ۳: شناسایی بوی کد
    ↓
فاز ۴: تدوین برنامه ری‌فاکتور
    ↓
فاز ۵: پیاده‌سازی تدریجی
    ↓
فاز ۶: بازبینی و تکرار
```

---

## فاز ۱: پژوهش و تحلیل

### اهداف
- درک ساختار و هدف کدبیس
- شناسایی دامنه ری‌فاکتور
- گردآوری زمینه درباره نیازمندی‌های کسب‌وکار

### پرسش‌هایی که باید از کاربر پرسید
پیش از شروع، این موارد را روشن کنید:

1. **دامنه**: کدام فایل‌ها/ماژول‌ها/توابع به ری‌فاکتور نیاز دارند؟
2. **اهداف**: می‌خواهید چه مشکلاتی را حل کنید؟ (خوانایی، کارایی، قابلیت نگهداری)
3. **محدودیت‌ها**: آیا بخش‌هایی وجود دارد که نباید تغییر کند؟
4. **فشار زمانی**: آیا این کار مانع کارهای دیگر شده است؟
5. **وضعیت تست**: آیا تست وجود دارد؟ آیا موفق هستند؟

### اقدامات
- [ ] کد هدف را بخوانید و درک کنید
- [ ] وابستگی‌ها و یکپارچگی‌ها را شناسایی کنید
- [ ] معماری فعلی را مستند کنید
- [ ] نشانه‌های بدهی فنی موجود (TODO، FIXME) را یادداشت کنید

### خروجی
یافته‌ها را به کاربر ارائه دهید:
- خلاصه ساختار کد
- نواحی مشکل‌دار شناسایی‌شده
- توصیه‌های اولیه
- **درخواست تأیید برای ادامه**

---

## فاز ۲: ارزیابی پوشش تست

### چرا تست اهمیت دارد
> «ری‌فاکتور بدون تست مثل رانندگی بدون کمربند ایمنی است.» — مارتین فاولر

تست‌ها **توانمندساز کلیدی** ری‌فاکتور ایمن هستند. بدون آن‌ها، خطر وارد کردن باگ وجود دارد.

### گام‌های ارزیابی

1. **بررسی تست‌های موجود**
   ```bash
   # جست‌وجوی فایل‌های تست
   find . -name "*test*" -o -name "*spec*" | head -20
   ```

2. **اجرای تست‌های موجود**
   ```bash
   # جاوااسکریپت/تایپ‌اسکریپت
   npm test

   # پایتون
   pytest -v

   # جاوا
   mvn test
   ```

3. **بررسی پوشش (در صورت وجود)**
   ```bash
   # جاوااسکریپت
   npm run test:coverage

   # پایتون
   pytest --cov=.
   ```

### نقطه تصمیم: پرسش از کاربر

**اگر تست‌ها وجود دارند و موفق‌اند:**
- به فاز ۳ بروید

**اگر تست‌ها موجود نیستند یا ناقص‌اند:**
گزینه‌ها را ارائه دهید:
1. ابتدا تست بنویسید (توصیه‌شده)
2. تست‌ها را به‌صورت تدریجی در حین ری‌فاکتور اضافه کنید
3. بدون تست ادامه دهید (پرخطر - نیازمند تأیید کاربر)

**اگر تست‌ها شکست می‌خورند:**
- توقف. پیش از ری‌فاکتور تست‌های شکست‌خورده را اصلاح کنید
- از کاربر بپرسید: آیا ابتدا تست‌ها را اصلاح کنیم؟

### راهنمای نوشتن تست (در صورت نیاز)

برای هر تابعی که ری‌فاکتور می‌شود، اطمینان حاصل کنید تست‌ها این موارد را پوشش می‌دهند:
- مسیر خوش‌بینانه (عملکرد عادی)
- موارد لبه‌ای (ورودی خالی، null، مرزها)
- سناریوهای خطا (ورودی نامعتبر، استثناها)

از چرخه «قرمز-سبز-ری‌فاکتور» استفاده کنید:
1. تست شکست‌خورده بنویسید (قرمز)
2. آن را موفق کنید (سبز)
3. ری‌فاکتور کنید

---

## فاز ۳: شناسایی بوی کد

### بوی کد چیست؟
نشانه‌های مشکلات عمیق‌تر در کد. آن‌ها باگ نیستند، بلکه نشانگر آن‌اند که کد می‌تواند بهتر شود.

### بوی‌های کد رایج برای بررسی

برای فهرست کامل به [references/code-smells.md](references/code-smells.md) مراجعه کنید.

#### مرجع سریع

| بوی کد | نشانه‌ها | تأثیر |
|-------|-------|--------|
| **متد بلند** | متدهای بیش از ۳۰ تا ۵۰ خط | درک، تست و نگهداری دشوار |
| **کد تکراری** | منطق یکسان در چند نقطه | اصلاح باگ در چند نقطه لازم است |
| **کلاس بزرگ** | کلاسی با مسئولیت‌های بیش از حد | نقض اصل مسئولیت واحد |
| **حسادت ویژگی** | متد از داده‌های کلاس دیگر بیشتر استفاده می‌کند | کپسوله‌سازی ضعیف |
| **وسواس نوع اولیه** | استفاده بیش از حد از انواع اولیه به‌جای اشیاء | مفاهیم دامنه جا افتاده |
| **فهرست پارامتر بلند** | متدهایی با ۴ پارامتر یا بیشتر | فراخوانی صحیح دشوار |
| **خوشه‌های داده** | اقلام داده یکسان که با هم ظاهر می‌شوند | انتزاع جا افتاده |
| **دستورات switch** | زنجیره‌های پیچیده switch/if-else | توسعه دشوار |
| **کلیت حدسی** | کد «محض احتیاط» | پیچیدگی غیرضروری |
| **کد مرده** | کد بی‌استفاده | سردرگمی، بار نگهداری |

### گام‌های تحلیل

1. **تحلیل خودکار** (در صورت وجود اسکریپت)
   ```bash
   python scripts/detect-smells.py <file>
   ```

2. **بازبینی دستی**
   - کد را به‌صورت نظام‌مند مرور کنید
   - هر بوی کد را همراه با مکان و شدت یادداشت کنید
   - بر اساس تأثیر دسته‌بندی کنید (بحرانی/بالا/متوسط/پایین)

3. **اولویت‌بندی**
   روی بوی‌هایی تمرکز کنید که:
   - توسعه فعلی را مسدود می‌کنند
   - باعث باگ یا سردرگمی می‌شوند
   - مسیرهای کدی را که بیشترین تغییر را دارند تحت تأثیر قرار می‌دهند

### خروجی: گزارش بوی کد

به کاربر ارائه دهید:
- فهرست بوی‌های شناسایی‌شده همراه با مکان‌ها
- ارزیابی شدت برای هرکدام
- ترتیب اولویت پیشنهادی
- **درخواست تأیید اولویت‌ها**

---

## فاز ۴: تدوین برنامه ری‌فاکتور

### انتخاب ری‌فاکتورها

برای هر بوی کد، ری‌فاکتور مناسب را از کاتالوگ انتخاب کنید.

برای فهرست کامل به [references/refactoring-catalog.md](references/refactoring-catalog.md) مراجعه کنید.

#### نگاشت بوی کد به ری‌فاکتور

| بوی کد | ری‌فاکتور(های) پیشنهادی |
|------------|---------------------------|
| متد بلند | استخراج متد، جایگزینی متغیر موقت با پرس‌وجو |
| کد تکراری | استخراج متد، بالا کشیدن متد، تشکیل متد الگو |
| کلاس بزرگ | استخراج کلاس، استخراج زیرکلاس |
| حسادت ویژگی | انتقال متد، انتقال فیلد |
| وسواس نوع اولیه | جایگزینی نوع اولیه با شیء، جایگزینی کد نوع با کلاس |
| فهرست پارامتر بلند | معرفی شیء پارامتر، حفظ کل شیء |
| خوشه‌های داده | استخراج کلاس، معرفی شیء پارامتر |
| دستورات switch | جایگزینی شرطی با چندریختی |
| کلیت حدسی | فروپاشی سلسله‌مراتب، درون‌خط کردن کلاس، حذف کد مرده |
| کد مرده | حذف کد مرده |

### ساختار برنامه

از قالب موجود در [templates/refactoring-plan.md](templates/refactoring-plan.md) استفاده کنید.

برای هر ری‌فاکتور:
1. **هدف**: چه کدی تغییر می‌کند
2. **بوی کد**: چه مشکلی را برطرف می‌کند
3. **ری‌فاکتور**: کدام تکنیک اعمال می‌شود
4. **گام‌ها**: ریزگام‌های تفصیلی
5. **ریسک‌ها**: چه چیزی ممکن است اشتباه پیش برود
6. **بازگشت**: چگونگی واگرد در صورت نیاز

### رویکرد مرحله‌ای

**حیاتی**: ری‌فاکتور را به‌تدریج و در قالب مراحل معرفی کنید.

**فاز الف: بردهای سریع** (ریسک کم، ارزش بالا)
- تغییر نام متغیرها برای خوانایی بیشتر
- استخراج کدهای تکراری آشکار
- حذف کدهای مرده

**فاز ب: بهبودهای ساختاری** (ریسک متوسط)
- استخراج متدها از توابع طولانی
- معرفی اشیای پارامتر
- انتقال متدها به کلاس‌های مناسب

**فاز ج: تغییرات معماری** (ریسک بالاتر)
- جایگزینی شرط‌ها با چندریختی
- استخراج کلاس‌ها
- معرفی الگوهای طراحی

### نقطه تصمیم: ارائه برنامه به کاربر

پیش از پیاده‌سازی:
- برنامه کامل ری‌فاکتور را نشان دهید
- هر فاز و ریسک‌هایش را توضیح دهید
- برای هر فاز تأیید صریح بگیرید
- **بپرسید**: «آیا با فاز الف ادامه دهم؟»

---

## فاز ۵: پیاده‌سازی تدریجی

### قاعده طلایی
> «تغییر → تست → سبز؟ → کامیت → گام بعدی»

### ریتم پیاده‌سازی

برای هر گام ری‌فاکتور:

1. **پیش‌بررسی**
   - تست‌ها قبول می‌شوند (سبز)
   - کد کامپایل می‌شود

2. **یک تغییر کوچک انجام دهید**
   - مکانیک‌های کاتالوگ را دنبال کنید
   - تغییرات را حداقلی نگه دارید

3. **راستی‌آزمایی**
   - تست‌ها را فوراً اجرا کنید
   - خطاهای کامپایل را بررسی کنید

4. **اگر تست‌ها قبول شوند (سبز)**
   - با پیام توصیفی کامیت کنید
   - به گام بعدی بروید

5. **اگر تست‌ها رد شوند (قرمز)**
   - فوراً متوقف شوید
   - تغییر را برگردانید
   - تحلیل کنید چه چیزی اشتباه شد
   - اگر ابهام داشت از کاربر بپرسید

### راهبرد کامیت

هر کامیت باید چنین باشد:
- **اتمیک**: یک تغییر منطقی
- **قابل بازگشت**: به‌راحتی برگشت‌پذیر
- **توصیفی**: پیام کامیت روشن

نمونه پیام‌های کامیت:
```
refactor: استخراج calculateTotal() از processOrder()
refactor: تغییر نام 'x' به 'customerCount' برای خوانایی
refactor: حذف متد بی‌استفادهٔ validateOldFormat()
```

### گزارش پیشرفت

پس از هر زیرفاز، به کاربر گزارش دهید:
- تغییرات انجام‌شده
- آیا تست‌ها همچنان قبول می‌شوند؟
- هر مشکلی که پیش آمده
- **بپرسید**: «با دستهٔ بعدی ادامه دهم؟»

---

## فاز ۶: بازبینی و تکرار

### چک‌لیست پس از ری‌فاکتور

- [ ] همهٔ تست‌ها قبول می‌شوند
- [ ] هیچ هشدار یا خطای جدیدی نیست
- [ ] کد با موفقیت کامپایل می‌شود
- [ ] رفتار تغییر نکرده است (راستی‌آزمایی دستی)
- [ ] مستندات در صورت نیاز به‌روزرسانی شده‌اند
- [ ] تاریخچهٔ کامیت‌ها تمیز است

### مقایسهٔ شاخص‌ها

تحلیل پیچیدگی را قبل و بعد اجرا کنید:
```bash
python scripts/analyze-complexity.py <file>
```

بهبودها را ارائه دهید:
- تغییر تعداد خطوط کد
- تغییر پیچیدگی سایکلوماتیک
- تغییر شاخص قابلیت نگهداری

### بازبینی کاربر

نتایج نهایی را ارائه دهید:
- خلاصهٔ همهٔ تغییرات
- مقایسهٔ کد قبل و بعد
- بهبود شاخص‌ها
- بدهی فنی باقی‌مانده
- **بپرسید**: «آیا از این تغییرات راضی هستید؟»

### گام‌های بعدی

با کاربر گفت‌وگو کنید:
- بوهای کد دیگری برای رسیدگی وجود دارد؟
- ری‌فاکتور پیگیری‌کننده برنامه‌ریزی شود؟
- تغییرات مشابه در جای دیگر اعمال شود؟

---

## راهنماهای مهم

### چه زمانی متوقف شویم و بپرسیم

همیشه وقتی موارد زیر پیش می‌آید توقف کنید و با کاربر مشورت کنید:
- در منطق کسب‌وکار ابهام دارید
- تغییر ممکن است بر APIهای خارجی اثر بگذارد
- پوشش تست کافی نیست
- تصمیم معماری مهمی لازم است
- سطح ریسک افزایش می‌یابد
- با پیچیدگی غیرمنتظره‌ای روبه‌رو می‌شوید

### قواعد ایمنی

1. **هرگز بدون تست ری‌فاکتور نکنید** (مگر آنکه کاربر صریحاً ریسک را بپذیرد)
2. **هرگز تغییرات بزرگ ندهید** - آن را به گام‌های ریز بشکنید
3. **هرگز اجرای تست را رد نکنید** بعد از هر تغییر
4. **اگر تست‌ها رد شوند هرگز ادامه ندهید** - ابتدا اصلاح یا بازگشت کنید
5. **هرگز فرض نکنید** - در صورت ابهام بپرسید

### کارهایی که نباید انجام داد

- ری‌فاکتور را با افزودن قابلیت ترکیب نکنید
- در بحران‌های محیط عملیاتی ری‌فاکتور نکنید
- کدی را که نمی‌فهمید ری‌فاکتور نکنید
- بیش از حد مهندسی نکنید - ساده نگه دارید
- همه‌چیز را یک‌جا ری‌فاکتور نکنید

---

## نمونه شروع سریع

### سناریو: متد طولانی با تکرار

**قبل:**
```javascript
function processOrder(order) {
  // ۱۵۰ خط کد شامل:
  // - منطق اعتبارسنجی تکراری
  // - محاسبات درون‌خطی
  // - مسئولیت‌های مخلوط
}
```

**گام‌های ری‌فاکتور:**

1. **از وجود تست اطمینان حاصل کنید** برای processOrder()
2. **اعتبارسنجی را استخراج کنید** به validateOrder()
3. **تست** - باید قبول شود
4. **محاسبه را استخراج کنید** به calculateOrderTotal()
5. **تست** - باید قبول شود
6. **اطلاع‌رسانی را استخراج کنید** به notifyCustomer()
7. **تست** - باید قبول شود
8. **بازبینی** - processOrder() اکنون ۳ تابع شفاف را هماهنگ می‌کند

**بعد:**
```javascript
function processOrder(order) {
  validateOrder(order);
  const total = calculateOrderTotal(order);
  notifyCustomer(order, total);
  return { order, total };
}
```

---

## منابع

- [کاتالوگ بوهای کد](references/code-smells.md) - فهرست کامل بوهای کد
- [کاتالوگ ری‌فاکتور](references/refactoring-catalog.md) - تکنیک‌های ری‌فاکتور
- [قالب برنامه ری‌فاکتور](templates/refactoring-plan.md) - قالب برنامه‌ریزی

## اسکریپت‌ها

- `scripts/analyze-complexity.py` - تحلیل شاخص‌های پیچیدگی کد
- `scripts/detect-smells.py` - تشخیص خودکار بوی کد

## تاریخچهٔ نسخه

- v1.0.0 (2025-01-15): انتشار اولیه با متدولوژی فاولر، رویکرد مرحله‌ای و نقاط مشورت با کاربر

---

**آخرین به‌روزرسانی**: ۴ اوت ۲۰۲۶
**نسخه Claude Code**: 2.1.220
**منابع**:
- https://code.claude.com/docs/en/skills
**مدل‌های سازگار**: Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 5.5, Claude Haiku 4.5