فهم الكود الموجود

يساعدك Verdent for VS Code على فهم قواعد الكود غير المألوفة من خلال الأسئلة بلغة طبيعية والاستكشاف الآلي. يعثر الوكيل الفرعي المدمج Explorer بسرعة على الملفات، ويبحث في أنماط الكود، ويجيب عن الأسئلة المعمارية دون استهلاك نافذة السياق الرئيسية لديك.

ما ستتعلمه

• استكشاف قواعد الكود غير المألوفة باستخدام الوكيل الفرعي Explorer
• طرح أسئلة حول بنية الكود وتنفيذه
• الحصول على شروحات مفصّلة للدوال والفئات والوحدات
• توليد التوثيق من الكود الموجود
• فهم بنية المشروع وتدفق البيانات
• إشراك أعضاء الفريق الجدد بكفاءة

المتطلبات الأساسية

قبل استخدام Verdent لفهم الكود:

• Visual Studio Code مع تثبيت امتداد Verdent
• قاعدة كود أو مساحة عمل مشروع مفتوحة في VS Code
• خطة اشتراك Verdent نشطة مع أرصدة متاحة

استكشاف قواعد الكود غير المألوفة

عندما تطرح أسئلة حول بنية قاعدة الكود أو تطلب البحث عن ملفات، يفوّض Verdent المهمة تلقائيًا إلى الوكيل الفرعي Explorer (@Explorer)، وهو متخصص فعّال من حيث استهلاك الرموز ومُحسَّن للاستكشاف السريع لقواعد الكود.

يقوم الوكيل الفرعي Explorer بسرعة بما يلي:

• العثور على الملفات المطابقة لأنماط أو أسماء معينة
• البحث في الكود عن كلمات مفتاحية أو دوال محددة
• الإجابة عن الأسئلة المعمارية حول قاعدة الكود
• تحديد أماكن تنفيذ الوظائف

أمثلة على أسئلة الاستكشاف:

What is the structure of this project?

Where is user authentication handled?

Find all API endpoint definitions

Show me where database queries are defined

يعمل Explorer بكفاءة في الخلفية، ويقدّم إجابات سريعة دون استهلاك نافذة السياق الرئيسية لديك. يعرض Verdent النتائج مع مسارات الملفات ومقتطفات الكود ذات الصلة.

الاستكشاف المتوازي للمهام المعقدة:

بالنسبة للمهام الاستكشافية المعقدة، يمكن تشغيل عدة وكلاء Explorer بشكل متوازٍ لتوفير الوقت، حيث يبحث كل منهم في جانب مختلف من قاعدة الكود في الوقت نفسه. يقوم Verdent بعد ذلك بتجميع النتائج في ملخص متماسك.

مثال:

Use the Explorer agent to find all places where we manually validate email addresses

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

طرح الأسئلة حول الكود الخاص بك

يجيب Verdent عمليًا عن أي سؤال حول قاعدة الكود الخاصة بك باستخدام اللغة الطبيعية. يفهم الذكاء الاصطناعي السياق ويقدّم شروحًا وتحليلات ورؤى مفصّلة.

Explain how authentication works in this project

What does the calculateTotal function do?

How are API requests handled?

What is the overall architecture of this application?

How do the components communicate with each other?

What design patterns are used in this codebase?

Why do you think Redux was chosen instead of Context API for state management?

What would happen if I changed the API timeout from 30s to 60s?

Is this validateUserInput function redundant?

Where is user data validated?

Show me all database queries in the project

What dependencies does this project have?

How does the quicksort algorithm work in the sortItems function?

What are the best practices for error handling in React components?

Explain the Observer pattern implementation in the EventEmitter class

شرح الدوال والفئات

يقدّم Verdent شروحًا مفصّلة لدوال أو فئات محددة من خلال تحليل تنفيذها ومعاملاتها وقيمها المُعادة واستخدامها في جميع أنحاء قاعدة الكود.

أمثلة:

Explain the UserAuth class

What does the processPayment function do?

Break down the ApiService class methods

ما يشرحه Verdent:

• الغرض: ما تحققه الدالة أو الفئة
• المعاملات: أنواع المدخلات والقيم المتوقعة والقيود
• أنواع القيم المُعادة: أنواع المخرجات والقيم المُعادة المحتملة
• المنطق الداخلي: كيفية عمل التنفيذ خطوة بخطوة
• التبعيات: الوحدات أو الدوال أو الخدمات الخارجية المستخدَمة
• أمثلة الاستخدام: كيفية استخدام الدالة/الفئة في أماكن أخرى من الكود الخاص بك

يتتبع Verdent مسار تنفيذ الكود، ويحدد الحالات الاستثنائية، ويشرح المنطق وراء خيارات التنفيذ.

توليد التوثيق

يولّد Verdent توثيقًا بتنسيقات متعددة تشمل تعليقات الكود المضمّنة (JSDoc، docstrings الخاصة بـ Python، وغيرها)، وملفات README، وتوثيق API، وأدلة البنية المعمارية.

استخدام Plan Mode للتوثيق

في Plan Mode، يمكن لـ Verdent أن:

• يحلل توثيقك الموجود لمطابقة أسلوبه وكثافته
• يطرح أسئلة توضيحية حول تفضيلات التنسيق (أسلوب التعليقات، مستوى التفاصيل، إدراج الأمثلة)
• يحلل قاعدة الكود لفهم أنماط التوثيق الحالية
• يعرض خطة توثيق تُظهر ما سيتم توثيقه وبأي أسلوب

مثال:

Generate JSDoc comments for all functions in the utils folder

يفحص Verdent تعليقات JSDoc الموجودة في مشروعك، ويطرح أسئلة حول التفضيلات (أوصاف المعاملات، إدراج أمثلة الاستخدام)، ثم يولّد توثيقًا يطابق الاصطلاحات المعتمدة لديك.

تنسيقات التوثيق المدعومة:

• التعليقات المضمّنة: JSDoc وdocstrings الخاصة بـ Python وJavadoc وتعليقات توثيق XML
• ملفات README: نظرة عامة على المشروع، وتعليمات الإعداد، وأدلة الاستخدام
• توثيق API: أوصاف نقاط النهاية، وتنسيقات الطلب/الاستجابة، وتفاصيل المصادقة
• أدلة البنية المعمارية: شروحات تصميم النظام، وعلاقات المكوّنات، ومخططات تدفق البيانات

تلخيص الملفات والوحدات

يحلل Verdent الملفات أو الوحدات ويلخّصها من خلال قراءة الكود وفهم بنيته وشرح غرضه بلغة واضحة.

أمثلة:

Summarize what the authMiddleware.js file does

Explain the purpose of the UserService module

What's the main responsibility of the PaymentController?

ما يقدّمه Verdent:

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

يقرأ Verdent الملف، ويحدد الدوال الرئيسية، ويتتبع التبعيات، ويشرح كيفية اندماج الكود ضمن بنية المشروع الأوسع.

فهم البنية المعمارية

يشرح Verdent البنية المعمارية من خلال أوصاف نصية مفصّلة، وعلاقات المكوّنات، وشروحات تدفق البيانات. ورغم أنه لا يولّد مخططات رسومية مباشرة، إلا أنه يمكنه إنشاء مخططات ASCII أو كود مخططات Mermaid يمكنك عرضه.

مثال:

Explain the architecture of this application and show component relationships

قد ينتج Verdent تمثيلًا بصيغة ASCII:

Frontend (React)
    ↓
API Layer (Express)
    ↓
Service Layer (Business Logic)
    ↓
Database Layer (PostgreSQL)

أو يولّد كود Mermaid للعرض:

graph TD
    A[React Frontend] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[User Service]
    C --> E[Database]
    D --> E

تشمل شروحات البنية المعمارية:

• تفاعلات المكوّنات: كيف تتواصل الأجزاء المختلفة من النظام
• تدفق البيانات: كيف تنتقل المعلومات عبر التطبيق
• الأنماط المعمارية: MVC، الخدمات المصغّرة، البنية الطبقية، إلخ
• حزمة التقنيات: الواجهة الأمامية، الخلفية، قاعدة البيانات، الخدمات الخارجية
• نقاط التكامل: API، طوابير الرسائل، الـ webhooks، الخدمات الخارجية من طرف ثالث
• أنماط قابلية التوسّع: موازنة الأحمال، التخزين المؤقت، تجزئة قواعد البيانات

يحلل Verdent بنية مشروعك، ويتتبع عمليات الاستيراد والتبعيات، ويحدد الأنماط، ويشرح القرارات المعمارية وراء تصميم نظامك.

إشراك أعضاء الفريق الجدد

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

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

أمثلة على أسئلة الإشراك:

What's the best starting point for understanding this codebase?

How does data flow from the API to the frontend?

Where should I look to understand the authentication system?

What are the naming conventions and code style guidelines used here?

يمكن لـ Verdent توليد:

• أدلة الإشراك: شروحات خطوة بخطوة لبنية قاعدة الكود
• خرائط المكوّنات: أدلة بصرية أو نصية تُظهر كيفية ارتباط المكوّنات ببعضها
• الأنماط الشائعة: توثيق الأنماط والاصطلاحات المستخدَمة بكثرة
• تعليمات الإعداد: كيفية تهيئة بيئة التطوير وتشغيل المشروع
• المهام الأولى: اقتراحات لمساهمات أولى بسيطة لاكتساب الإلمام بالمشروع

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

أفضل الممارسات

اطّلع أيضًا على