# تحسين الكود وإعادة هيكلته (/ar/docs/verdent-for-vscode/task-based-guides/refactoring)

> أفضل الممارسات لتحسين الكود وإعادة هيكلته باستخدام Verdent



يساعدك Verdent for VS Code على إعادة هيكلة الكود وتحسينه بأمان عبر ملفات متعددة مع الحفاظ على الوظائف. باستخدام Plan Mode مع الوكيل الفرعي Explorer، يمكنك تحديد جميع الملفات المتأثرة قبل إجراء أي تغييرات، مما يضمن إعادة هيكلة شاملة دون إغفال أي حالة.

### ما ستتعلمه [#ما-ستتعلمه]

* طلب عمليات إعادة هيكلة فعالة تركّز على النتائج، لا على التنفيذ
* إعادة هيكلة آمنة عبر ملفات متعددة مع إدارة التبعيات
* طلب تحسينات جودة الكود واقتراحات التحسين
* التعامل مع مشاريع إعادة الهيكلة واسعة النطاق بأسلوب متعدد المراحل
* تحسين الأداء من خلال تحسينات خوارزمية ومعمارية
* الحفاظ على وظائف الكود أثناء عمليات إعادة الهيكلة

### المتطلبات الأساسية [#المتطلبات-الأساسية]

قبل إعادة الهيكلة باستخدام Verdent:

* Visual Studio Code مع تثبيت امتداد Verdent
* قاعدة كود أو مساحة عمل مشروع مفتوحة في VS Code
* خطة اشتراك نشطة في Verdent مع أرصدة متاحة
* يُفضّل استخدام نظام التحكم بالإصدارات (Git) للتراجع الآمن عند الحاجة

***

## طلب عمليات إعادة هيكلة فعالة [#طلب-عمليات-إعادة-هيكلة-فعالة]

صِف **ما تريد تحسينه ولماذا**، بدلاً من **كيفية إصلاحه**. اترك Verdent يحلل الكود ويقترح أفضل نهج بناءً على أنماط مشروعك.

**طلبات إعادة هيكلة فعالة:**

ركّز على النتيجة التي تريدها، لا على التنفيذ:

```
Refactor the UserController to improve readability and reduce duplication
```

```
This authentication logic is scattered across multiple files. Consolidate it into a single module
```

```
Improve error handling in the API layer to be more consistent and informative
```

يحلل Verdent الكود، ويحدد جميع الملفات المتأثرة، ويفحص الأنماط، ويقترح استراتيجيات إعادة هيكلة محددة تتماشى مع اتفاقيات قاعدة الكود لديك.

**أفضل ممارسة: استخدام Plan Mode**

ابدأ طلبات إعادة الهيكلة في Plan Mode. سيقوم Verdent بما يلي:

1. تحليل الكود وتحديد جميع الملفات المتأثرة
2. عرض خطة إعادة هيكلة مفصلة قبل إجراء أي تغييرات
3. طرح أسئلة توضيحية حول تفضيلات التنفيذ
4. عرض ما سيتغير بالضبط وبأي ترتيب
5. السماح لك بمراجعة النهج وتنقيحه

**مثال باستخدام Plan Mode:**

```
In Plan Mode: Refactor authentication logic to use a centralized authentication utility
```

سيقوم Verdent بما يلي:

* استخدام Explorer لإيجاد جميع مواقع كود المصادقة
* تحديد الأنماط والتناقضات
* اقتراح واجهة مصادقة موحدة
* عرض الملفات التي سيتم تعديلها
* شرح تسلسل إعادة الهيكلة

يمكنك طلب حفظ Verdent للخطة في ملف `plan.md` لمراجعة إضافية ومناقشة الفريق قبل التنفيذ.

**استخدام Explorer لعمليات بحث شاملة:**

بالنسبة لعمليات إعادة الهيكلة المعقدة، اطلب صراحة من Verdent استخدام وكيل Explorer للبحث بدقة:

```
Use the Explorer agent to find all places where we manually validate email addresses, then refactor them to use a centralized validation utility
```

هذا يضمن أن يكتشف Verdent كل موقع يحتاج إلى تحديث، مما يمنع إعادة هيكلة غير متسقة عبر قاعدة الكود.

<Tip>
  يُعد Plan Mode ضروريًا لإعادة الهيكلة. فهو يمنع المفاجآت من خلال عرض ما سيتغير بالضبط قبل التنفيذ، ويتيح لك تنقيح النهج بناءً على الاعتبارات المعمارية.
</Tip>

***

## إعادة الهيكلة عبر ملفات متعددة [#إعادة-الهيكلة-عبر-ملفات-متعددة]

يعيد Verdent هيكلة الكود عبر ملفات متعددة مع الحفاظ على عبارات الاستيراد والتبعيات والمراجع بين الملفات. فهو يحدد جميع الملفات المتأثرة، ويحدّثها بالترتيب الصحيح، ويضمن الاتساق في جميع أنحاء قاعدة الكود.

**كيف تعمل إعادة الهيكلة عبر ملفات متعددة:**

1. **مرحلة الاكتشاف**: يجد Verdent (باستخدام Explorer) جميع الملفات التي تحتاج إلى تغيير
2. **تحليل التبعيات**: تحديد التبعيات بين الملفات لتحديد ترتيب التحديث
3. **إنشاء الخطة**: عرض جميع الملفات المراد تعديلها وتسلسل التغييرات
4. **التحديثات المتسلسلة**: تعديل الملفات وفق ترتيب التبعية (مثلًا الأنواع قبل المكونات التي تستخدمها)
5. **إدارة الاستيراد**: تحديث عبارات الاستيراد والتصدير والمراجع بين الملفات تلقائيًا
6. **التحقق**: التأكد من اتساق التغييرات عبر جميع الملفات

<Note>
  تحافظ إعادة الهيكلة عبر ملفات متعددة على الوظائف من خلال تتبع تلقائي للتبعيات، إذ يحدّث Verdent جميع الملفات المتأثرة بشكل ذري.
</Note>

**مثال:**

```
Rename the User interface to UserProfile across the entire project
```

سيقوم Verdent بما يلي:

* إيجاد جميع الملفات التي تستورد أو تستخدم `User`
* تحديد تعريفات الأنواع والتنفيذات وأماكن الاستخدام
* تحديث تعريفات الأنواع أولًا، ثم التنفيذات، ثم أماكن الاستخدام
* تعديل جميع عبارات الاستيراد
* ضمان الاتساق في جميع أنحاء قاعدة الكود

**استخدم Plan Mode لمراجعة النطاق:**

قبل تنفيذ إعادة الهيكلة عبر ملفات متعددة، راجع النطاق الكامل في Plan Mode:

```
In Plan Mode: Extract the authentication logic from UserController into a separate AuthService
```

سيعرض Verdent:

* الملفات التي سيتم إنشاؤها (خدمة AuthService الجديدة)
* الملفات التي سيتم تعديلها (UserController وكل من يستوردها)
* الكود الذي سينتقل من UserController إلى AuthService
* كيفية تحديث عبارات الاستيراد والتبعيات

هذا يمنع التوسع العرضي في النطاق ويضمن فهمك للتأثير الكامل قبل المتابعة.

***

## طلب تحسينات جودة الكود [#طلب-تحسينات-جودة-الكود]

لا يقترح Verdent تحسينات بشكل استباقي دون أن يُطلب منه ذلك. مع ذلك، يمكنك طلب مراجعات لجودة الكود واقتراحات للتحسين في أي وقت.

<Tabs>
  <Tab title="مراجعات عامة">
    اطلب مراجعات شاملة لجودة الكود:

    ```
    Review this code for potential improvements
    ```

    ```
    Suggest ways to improve code quality in the UserService module
    ```

    ```
    Are there any performance optimizations we could make here?
    ```

    ```
    Analyze the PaymentController for maintainability issues
    ```

    يحلل Verdent الكود ويقدّم اقتراحات محددة بشأن:

    * **قابلية القراءة**: تسمية المتغيرات، تفكيك الدوال، وضوح التعليقات
    * **الأداء**: تعقيد الخوارزميات، العمليات الزائدة، فرص التخزين المؤقت
    * **قابلية الصيانة**: تكرار الكود، الاقتران، فصل الاهتمامات
    * **أفضل الممارسات**: أنماط التصميم، معالجة الأخطاء، تغطية الاختبارات
    * **الأمان**: التحقق من صحة المدخلات، فحوصات المصادقة، تسريب البيانات
  </Tab>

  <Tab title="مراجعات موجّهة">
    للحصول على ملاحظات موجّهة، أشِر إلى ملفات محددة:

    ```
    @services/UserService.js Review this module for dependency injection improvements
    ```

    ```
    @controllers/PaymentController.js Identify opportunities to reduce complexity
    ```

    يفحص Verdent الكود المحدد في سياق أنماط مشروعك ويقدّم توصيات قابلة للتنفيذ.
  </Tab>
</Tabs>

***

## مشاريع إعادة الهيكلة واسعة النطاق [#مشاريع-إعادة-الهيكلة-واسعة-النطاق]

بالنسبة لإعادة الهيكلة واسعة النطاق، استخدم Plan Mode مع **نهج متعدد المراحل** للحصول على أفضل النتائج الموثوقة. يقسّم Verdent عملية إعادة الهيكلة إلى مراحل قابلة للإدارة، مما يتيح لك مراجعة كل مرحلة والموافقة عليها قبل المتابعة.

**سير عمل إعادة هيكلة متعدد المراحل:**

#### المرحلة 1: التحليل الأولي [#المرحلة-1-التحليل-الأولي]

استخدم Plan Mode مع وكيل Explorer لتحديد جميع الملفات والتبعيات المتأثرة:

```
In Plan Mode: Use Explorer to analyze our codebase and create a plan to replace our custom authentication with OAuth 2.0
```

يقوم Verdent بتحليل شامل:

* تحديد جميع الأكواد المتعلقة بالمصادقة
* رسم خريطة للتبعيات ونقاط التكامل
* تقييم التعقيد ومناطق الخطر
* اقتراح تقسيم المراحل

#### المرحلة 2: التخطيط للمراحل [#المرحلة-2-التخطيط-للمراحل]

ينشئ Verdent خطة متعددة المراحل للمراجعة:

**مثال على خطة:**

* **المرحلة 1**: إضافة مكتبة OAuth وضبط نقاط النهاية
* **المرحلة 2**: تحديث نموذج المستخدم ومخطط قاعدة البيانات
* **المرحلة 3**: ترحيل منطق المصادقة الحالي
* **المرحلة 4**: إزالة كود المصادقة المهمَل
* **المرحلة 5**: تحديث الاختبارات والوثائق

تتضمن كل مرحلة:

* الملفات المراد تعديلها
* التعقيد المقدَّر
* التبعيات على المراحل السابقة
* تقييم المخاطر

#### المرحلة 3: التنفيذ مرحلة تلو الأخرى [#المرحلة-3-التنفيذ-مرحلة-تلو-الأخرى]

نفّذ مرحلة واحدة في كل مرة، مع الاختبار بين المراحل:

1. الموافقة على المرحلة 1 في Plan Mode
2. الانتقال إلى Agent Mode والتنفيذ
3. الاختبار الشامل للتحقق من عمل المرحلة 1
4. العودة إلى Plan Mode للمرحلة 2
5. التكرار حتى اكتمال جميع المراحل

#### المرحلة 4: التنقيح التكراري [#المرحلة-4-التنقيح-التكراري]

راجع النتائج بعد كل مرحلة. إذا ظهرت مشكلات:

* عدّل الخطة للمراحل المتبقية
* أضف مراحل تصحيحية عند الحاجة
* نقّح النهج بناءً على الاكتشافات

يضمن هذا النهج المرحلي الأمان ويتيح تصحيح المسار في حال ظهور مشكلات أثناء مشاريع إعادة الهيكلة الكبيرة.

<Note>
  يجب دائمًا إجراء إعادة الهيكلة واسعة النطاق باستخدام نظام التحكم بالإصدارات. قم بالـ commit بعد كل مرحلة حتى تتمكن من التراجع إذا ظهرت مشكلات دون فقدان كل التقدم المحرز.
</Note>

***

## تحسين الأداء [#تحسين-الأداء]

يحلل Verdent الكود بحثًا عن اختناقات الأداء ويقترح تحسينات تشمل تحسين تعقيد الخوارزميات، وبنى بيانات فعالة، وتقليل استخدام الموارد.

<Tabs>
  <Tab title="تحسين الخوارزميات">
    حسّن التعقيد الخوارزمي:

    ```
    Analyze the performance of this data processing function and suggest improvements
    ```

    ```
    Can we improve the time complexity of this search algorithm?
    ```

    **ما الذي يحدده Verdent:**

    * **تعقيد الخوارزميات**: حلقات O(n²)، التكرارات المتداخلة، عمليات البحث غير الفعالة
    * **الحسابات الزائدة**: العمليات الحسابية المتكررة، العمليات غير الضرورية
    * **مشكلات الذاكرة**: تسريبات الذاكرة، التخصيصات المفرطة، الاحتفاظ بكائنات كبيرة

    **مثال:**

    ```
    Optimize the searchProducts function that's currently O(n²)
    ```

    يحلل Verdent الدالة، ويحدد سبب عدم الكفاءة (حلقات متداخلة أو عمليات بحث خطية متكررة)، ويقترح تحسينات محددة:

    * استبدال الحلقة المتداخلة بخريطة تجزئة (hash map) للبحث بتعقيد O(n)
    * استخدام البحث الثنائي بعد الفرز للحصول على تعقيد O(log n)
    * تخزين النتائج المحسوبة مؤقتًا لتجنب الحسابات الزائدة
    * تنفيذ التخزين المؤقت (memoization) للعمليات المكلفة

    يتضمن الرد:

    * **التعقيد الحالي**: شرح سبب بطء الكود الحالي
    * **الحل المقترح**: تغيير محدد في الخوارزمية أو بنية البيانات
    * **مكسب الأداء**: التحسين المقدَّر (مثلًا O(n²) ← O(n log n))
    * **المفاضلات**: اعتبارات استخدام الذاكرة، وتعقيد الكود، وقابلية الصيانة
  </Tab>

  <Tab title="تحسين المكونات">
    حسّن مكونات واجهة المستخدم والعرض (rendering):

    ```
    Optimize this component to reduce unnecessary re-renders
    ```

    **ما الذي يحدده Verdent:**

    * **أداء الواجهة الأمامية**: عمليات إعادة العرض غير الضرورية، أحجام الحزم الكبيرة، العمليات المعيقة
    * **دورة حياة المكوّن**: اعتماديات useEffect غير الفعالة، غياب التخزين المؤقت (memoization)
    * **إدارة الحالة**: تحديثات الحالة الزائدة، تمرير الخصائص عبر مستويات متعددة (prop drilling)

    يحلل Verdent مكوّنك ويقترح تحسينات مثل React.memo وuseMemo وuseCallback أو تقسيم المكونات.
  </Tab>

  <Tab title="تحسين API وقاعدة البيانات">
    حدد وأصلح اختناقات API وقاعدة البيانات:

    ```
    Identify performance bottlenecks in the API request handler
    ```

    **ما الذي يحدده Verdent:**

    * **أداء قاعدة البيانات**: استعلامات N+1، الفهارس المفقودة، الوصلات (joins) غير الفعالة
    * **أداء API**: نقاط النهاية البطيئة، جلب بيانات غير فعال، غياب التخزين المؤقت

    يفحص Verdent أنماط الاستعلام، ويقترح فهارس لقاعدة البيانات، واستراتيجيات تخزين مؤقت، وتقنيات تحسين API.
  </Tab>
</Tabs>

<Tip>
  لتحسين الأداء، وفّر سياقًا حول أحجام البيانات المعتادة وقيود الأداء. هذا يساعد Verdent على اقتراح حلول مناسبة لحجم مشروعك (مثلًا 100 عنصر مقابل مليون عنصر).
</Tip>

<Tip>
  قِس الأداء قبل التحسين، وقِس الأثر بعده للتأكد من أن التحسينات تحقق تحسنًا فعليًا وملموسًا.
</Tip>

***

## الحفاظ على الوظائف أثناء إعادة الهيكلة [#الحفاظ-على-الوظائف-أثناء-إعادة-الهيكلة]

يهدف Verdent إلى الحفاظ على وظائف الكود أثناء إعادة الهيكلة من خلال الحفاظ على نفس المدخلات والمخرجات والسلوك مع تحسين التنفيذ الداخلي.

**كيف يحافظ Verdent على الوظائف:**

* **تحليل المدخلات/المخرجات**: تحديد توقيعات الدوال، وعقود API، والسلوكيات المتوقعة
* **الوعي بالاختبارات**: اعتبار الاختبارات الحالية مواصفات سلوكية
* **تغييرات متحفظة**: إجراء أقل تغييرات ممكنة لتحقيق هدف إعادة الهيكلة
* **التحقق**: يمكنه توليد أو تشغيل اختبارات للتحقق من الحفاظ على الوظائف

**أفضل الممارسات لإعادة الهيكلة الآمنة:**

1. **اختبر دائمًا الكود المُعاد هيكلته** - حتى مع تحليل Verdent، يتحقق الاختبار اليدوي أو التلقائي من الحفاظ على الوظائف، خصوصًا في عمليات إعادة الهيكلة المعقدة

2. **استخدم نظام التحكم بالإصدارات** - قم بالـ commit قبل إعادة الهيكلة حتى تتمكن من التراجع في حال ظهور مشكلات

3. **أعد الهيكلة تدريجيًا** - قسّم عمليات إعادة الهيكلة الكبيرة إلى خطوات أصغر، واختبر بعد كل تغيير

4. **راجع التغييرات بعناية** - افحص الفروقات (diff) لفهم ما تغيّر ولماذا

5. **استخدم Plan Mode لعمليات إعادة الهيكلة المعقدة** - راجع النهج قبل التنفيذ لاكتشاف المشكلات المحتملة

**مثال: طلب إعادة هيكلة آمن**

```
Refactor the calculateOrderTotal function to use a more maintainable structure, but ensure it produces identical results for all input cases
```

سيقوم Verdent بما يلي:

* تحليل التنفيذ الحالي والحالات الحدّية
* اقتراح بنية معاد هيكلتها
* شرح سبب تكافؤ النسخة المُعاد هيكلتها
* اقتراح حالات اختبار للتحقق من التكافؤ

**عندما قد تتغير الوظيفة:**

في بعض الحالات، تُغيّر إعادة الهيكلة السلوك عمدًا (إصلاح أخطاء، تحسين التحقق من الصحة). صرّح بذلك بوضوح:

```
Refactor the email validation function to correctly handle international domains, which the current implementation doesn't support
```

هذا يوضّح أن التغيير السلوكي متوقَّع ومقصود.

***

## أفضل الممارسات [#أفضل-الممارسات]

<Accordion title="صِف المشكلة، لا الحل">
  دع Verdent يحلل الكود ويقترح أفضل نهج لإعادة الهيكلة بدلًا من فرض تغييرات محددة.
</Accordion>

<Accordion title="استخدم دائمًا Plan Mode لإعادة الهيكلة">
  راجع الخطة الكاملة قبل التنفيذ. هذا يمنع المفاجآت ويتيح لك تنقيح النهج بناءً على الاعتبارات المعمارية.
</Accordion>

<Accordion title="استخدم Explorer صراحةً لعمليات البحث الشاملة">
  لإعادة هيكلة شاملة، اطلب من Verdent استخدام Explorer لإيجاد جميع الحالات: "استخدم Explorer للعثور على كل معالجة يدوية للأخطاء، ثم أعد الهيكلة لاستخدام أداة الأخطاء الخاصة بنا."
</Accordion>

<Accordion title="قسّم عمليات إعادة الهيكلة الكبيرة إلى مراحل">
  الأساليب متعددة المراحل مع الاختبار بين المراحل أكثر أمانًا وأسهل إدارة من محاولة تنفيذ كل شيء دفعة واحدة.
</Accordion>

<Accordion title="اختبر بين المراحل">
  تحقق من عمل كل مرحلة قبل الانتقال إلى التالية. هذا يعزل المشكلات ويمنع تفاقمها.
</Accordion>

<Accordion title="قم بالـ commit بشكل متكرر">
  استخدم نظام التحكم بالإصدارات لإنشاء نقاط تفتيش بعد كل مرحلة أو تغيير رئيسي. هذا يتيح التراجع الآمن دون فقدان كل التقدم المحرز.
</Accordion>

<Accordion title="احفظ الخطط لمراجعة الفريق">
  بالنسبة لعمليات إعادة الهيكلة المهمة، اطلب من Verdent حفظ الخطة في `plan.md` لمناقشة الفريق قبل التنفيذ.
</Accordion>

<Accordion title="وفّر سياقًا للتحسين">
  عند طلب تحسينات الأداء، أدرج معلومات حول أحجام البيانات وقيود الأداء والمفاضلات المقبولة.
</Accordion>

***

## اطّلع أيضًا على [#اطّلع-أيضًا-على]

<CardGroup cols="2">
  <Card title="الاختبار وتصحيح الأخطاء" icon="bug" href="/docs/verdent-for-vscode/task-based-guides/testing-debugging">
    أنشئ اختبارات للتحقق من صحة عمل الكود المُعاد هيكلته
  </Card>

  <Card title="فهم الكود" icon="book" href="/docs/verdent-for-vscode/task-based-guides/understanding-code">
    حلّل بنية الكود قبل إعادة الهيكلة لفهم التأثير
  </Card>
</CardGroup>