---
title: "التعليقات المتبقية من الأوامر"
type: "ai-smell"
slug: "prompt-residue-comments"
url: "http://localhost:3000/ar/ai-smells/prompt-residue-comments.md"
category: "الوضوح"
description: "التعليقات التي تمثل مخلفات محادثة التوليد — مثل إعادة صياغة الأوامر الموجهة، والشرح خطوة بخطوة، والالتفاتات الحوارية الجانبية، وحذف الأكواد المؤقت مثل `// ... rest of the code here` — والتي تم حفظها في الكود المصدري بدلاً من التوثيق الحقيقي."
---
# التعليقات المتبقية من الأوامر

> التعليقات التي تمثل مخلفات محادثة التوليد — مثل إعادة صياغة الأوامر الموجهة، والشرح خطوة بخطوة، والالتفاتات الحوارية الجانبية، وحذف الأكواد المؤقت مثل `// ... rest of the code here` — والتي تم حفظها في الكود المصدري بدلاً من التوثيق الحقيقي.

## Signs and Symptoms

يكتشف المراجع التعليقات المتبقية من الأوامر عندما توثق التعليقات المحادثة التي أنتجت الكود بدلاً من الكود نفسه. أربع علامات، وغالباً ما تحدث معاً:

* **إعادة صياغة الأمر الموجه** — تعليق يعيد صياغة الطلب حرفياً (مثل `// دالة لجمع رقمين وإرجاع النتيجة`) فوق دالة مسماة بوضوح `add`.
* **شرح خطوات الكود** — شرح تفصيلي سطر بسطر لعمليات برمجية بديهية (مثل `// خطوة 1: الدوران عبر المصفوفة`، أو `// زيادة i بمقدار 1` فوق السطر `i++`).
* **الالتفاتات الحوارية الجانبية** — ملاحظات موجهة إليك بضمير المخاطب وزمن المضارع (مثل `// حسب طلبك، إليك المعالج المحدث`، `// بالتأكيد! إليك الحل`، `// ملاحظة: استبدله بمفتاح واجهة برمجة التطبيقات الحقيقي`).
* **الحذف / بقايا العناصر النائبة** — ترك عبارات مثل `// ... بقية الكود هنا`، أو `// احتفظ بالمنطق الحالي لديك`، أو `// كودك هنا`، أو `// TODO: تطبيق معالجة الأخطاء` في الكود المصدري المحفوظ.

```ts
// دالة لجمع رقمين وإرجاع النتيجة   <- يعيد صياغة الأمر الموجه
function add(a: number, b: number): number {
  // خطوة 1: جمع الرقمين                        <- يشرح الواضح
  const sum = a + b;
  return sum; // return the sum
}

// حسب طلبك، إليك المعالج المحدث            <- التفات حواري موجه إليك
export async function handler(req: Req, res: Res) {
  // ... احتفظ بمنطق التحقق الحالي هنا ...   <- حذف: تم إسقاط كود حقيقي
  // TODO: تطبيق معالجة الأخطاء                     <- عنصر نائب تم شحنه كما هو
  const user = await db.users.find(req.params.id);
  res.json(user);
}

```

سطر الحذف هو السطر الخطير: فهو يُقرأ كتوثيق ولكنه في الواقع تعليمات للبشر للصق كود أسقطه النموذج — وإذا قمت بتطبيق الكتلة حرفياً، فسوف يختفي التحقق الحالي من الصحة بصمت. وجدت Ox Security أن ظاهرة "التعليقات في كل مكان" تحدث بنسبة **90-100%** في الأكواد المولدة بالذكاء الاصطناعي في دراستها التي شملت أكثر من 300 مستودع، واصفة إياها بعلامات "تبدو مفيدة ولكنها تدعم الذكاء الاصطناعي نفسه بشكل أساسي، مما يسبب فوضى في المستودعات".

## Reasons for the Problem

**لماذا تصدرها النماذج؟**

* **محاكاة الرمز التالي لمجموعات بيانات الدروس البرمجية.** يمتلئ مزيج بيانات التدريب بمقالات المدونات وإجابات StackOverflow والتوثيقات حيث يتم شرح كل سطر كود للمتعلم. يعيد النموذج إنتاج ذلك الأسلوب التعليمي — المتمثل في شرح الكود وإعادة صياغة النية — لأنها التكملة الأكثر احتمالاً إحصائياً، وليس لأن المستودع المحيط يحتاج إليها.
* **تسرب السجل الحواري / التملق.** يتم ضبط المساعدين عبر RLHF ليكونوا توضيحيين ولطيفين في _قناة المحادثة (chat)_. ويتسرب هذا الأسلوب الحواري الموجه بضمير المخاطب إلى _قناة الكود_، مما ينتج التفاتات جانبية مثل "بناءً على طلبك..." و"ملاحظة: يجب عليك..." والتي لا معنى لها بمجرد فصل الكود عن المحادثة.
* **شرح التفكير البرمجي كتعليقات.** تقوم النماذج بكتابة خطتها البرمجية خطوة بخطوة ("الخطوة 1... الخطوة 2...") كتعليقات مدمجة — وهو تسرب لسلسلة التفكير (chain-of-thought) يتجمد داخل الملف.
* **الحذف أداة حوارية يساء تطبيقها.** في ردود المحادثة، يعتبر وضع `// ... الباقي دون تغيير ...` طريقة مهذبة لتجنب إعادة طباعة ملف كامل. ولكن عند لصق هذا الرد أو تطبيقه تلقائياً على ملف حقيقي، تصبح الأداة الحوارية بقايا حرفية متبقية — وفقداناً حقيقياً للبيانات.
* **غياب سياق المستودع، مما يجعله يعيد صياغة الأمر الموجه.** في غياب تذكرة العمل (ticket)، ونطاق العمل، والسبب الحقيقي لـ "لماذا"، لا يملك النموذج شيئاً حقيقياً ليقوله في التعليق، لذا يلجأ إلى إعادة صياغة الشيء الوحيد الذي يملكه: أمرك الموجه. تصف Ox هذه التعليقات بأنها "علامات داخلية للتنقل عبر حدود السياق... واعتماد على الذاكرة قصيرة المدى بدلاً من الفهم الحقيقي".

**لماذا يسبب ضرراً؟**

* **عبء المراجعة.** كل سطر شرح هو مجرد ضوضاء يتعين على المطور البشري تخطيها أثناء القراءة. صياغة Ox للموضوع: الذكاء الاصطناعي "يكتب الكود كالمطور المبتدئ" بسرعة الآلة، ولا يمكن للمراجعة البشرية "التوسع لمواكبة مخرجات الذكاء الاصطناعي" — وتجعل التعليقات المتبقية مراجعة كل فرق (diff) أكثر تكلفة في الوقت الذي تتزايد فيه الفروقات.
* **الصحة / فقدان البيانات.** تتسبب العناصر النائبة للحذف (مثل `// ...الكود الحالي...`) في إسقاط كود حقيقي عندما يتم تطبيق الكتل البرمجية بشكل أعمى.
* **تعفن التعليقات.** تكرر تعليقات إعادة صياغة الأوامر نية الكود في نص نثري؛ وينحرف هذا النص النثري مع تغير الكود، مما يترك توثيقاً مضللاً تماماً — وهو ما يمثل رائحة \*التعليقات كمعطر جو للكود السيئ\* الكلاسيكية التي وصفها Fowler.
* **عدم اكتمال مخفي.** تعليق `// TODO: implement error handling` هو إشارة من النموذج بأنه عمل عند حافة كفاءته وقدرته؛ وعند شحنه كما هو، فإنه يمثل منطقاً غير مكتمل متخفياً في شكل مهمة قيد التتبع.
* **مؤشرات أمنية.** عادة ما يستقر تعليق `// استبدله بمفتاح واجهة برمجة التطبيقات الحقيقي` بجانب بيانات اعتماد وهمية مكتوبة مباشرة — مما يحدد السطر الذي يهتم به الماسح الأمني (والمهاجم) بدقة.

## Treatment

**تكتيكات صياغة الأوامر والتوليد**

* قيّد أسلوب التسجيل الحواري: _"أخرج الملف كاملاً. لا تختصر أبداً بـ `// ...`، أو `// بقية الكود`، أو `// الكود الحالي`. لا تشرح الخطوات الواضحة — علّق فقط على المبررات غير البديهية (السبب). لا تضع التفاتات حوارية جانباً؛ فهذا الكود يذهب مباشرة إلى المستودع"_.
* اطلب **ملف فروقات موحد (unified diff)** بدلاً من مقطع ملفوف بالنصوص النثرية، بحيث تكون عمليات الحذف صريحة وقابلة للتطبيق بدلاً من مجرد الإشارة إليها بتعليق حذف.
* اطلب من النموذج تشغيل المنسق وإعدادات الفحص لديك (مثل قاعدة `no-warning-comments` مع مصطلحات مخصصة) والإبلاغ عن النتيجة — فإغلاق حلقة التقييم عبر أداة الفحص يلتقط بقايا العناصر النائبة و TODO تلقائياً.
* أضف بوابة فحص pre-commit أو CI للبحث عن علامات البقايا (مثل `rest of the code`، و `your code here`، و `existing code`، و `As requested`، و `Step \d`) وتعاَمَل مع علامات الحذف كـ **مانع صارم للدمج**، لأنها تعني غالباً إسقاط كود حقيقي بصمت.

**إعادة الهيكلة**

احذف الالتفاتات الحوارية الجانبية وشرح الخطوات تماماً. وحيثما يعيد تعليق صياغة _ما يفعله_ الكود ببساطة، فهذه إشارة لجعل الكود يوثق نفسه بنفسه — طبق **استخراج الدالة (Extract Function)** و**إعادة التسمية (Rename)** بحيث يحمل الاسم الغرض منه، ثم احتفظ فقط بالتعليقات التي تشرح _السبب_ غير البديهي (نصيحة Fowler: _أزل التعليقات التي تعمل كمعطر جو للأسماء السيئة_).

```ts
// قبل — مخلفات الأمر الموجه
// إنشاء دالة للتحقق من صحة بريد إلكتروني باستخدام تعبير نمطي (regex)
function validateEmail(input) {
  // فحص ما إذا كانت المدخلات تطابق نمط البريد الإلكتروني
  const re = /^[^@]+@[^@]+\.[^@]+$/;
  // إرجاع true أو false
  return re.test(input);
}

```

```ts
// بعد — الاسم يحمل الغرض؛ والتعليق الوحيد يشرح السبب غير الواضح
const EMAIL_RE = /^[^@]+@[^@]+\.[^@]+$/; // فضفاض عمداً: نلتقط فقط الأخطاء المطبعية قبل الإرسال، وليس معيار RFC 5322
const isValidEmail = (input: string): boolean => EMAIL_RE.test(input);

```

بالنسبة لبقايا الحذف، لا تقم أبداً بتطبيق الكتلة كما كتبت — بل قارنها بالملف الحالي واستعد ما أسقطه النموذج. وبالنسبة لتعليق `// TODO: implement …`، إما أن تكمل المنطق أو تحوله إلى مشكلة يتم تتبعها في نظام تتبع المهام واجعل بناء الكود يفشل عند مواجهة مصطلح العنصر النائب حتى لا يتم شحنه كما هو.

## Detected by

- **ESLint** `no-warning-comments` — تمييز تعليقات التحذير TODO/FIXME/XXX والمصطلحات المخصصة القابلة للإعداد — عيّن خيار `terms` لالتقاط بقايا العناصر النائبة مثل "your code here" أو "rest of the code". (https://eslint.org/docs/latest/rules/no-warning-comments)
- **SonarQube / SonarSource** `S125` — يجب عدم تعطيل أقسام الكود كتعليقات — تمييز الكتل المعطلة المحذوفة أو المتبقية كتعليقات. (https://rules.sonarsource.com/javascript/RSPEC-125/)
- **SonarQube / SonarSource** `S1135` — تتبع استخدام وسوم "TODO" — يظهر بقايا وسوم TODO المؤقتة المشحونة ككود. (https://rules.sonarsource.com/javascript/RSPEC-1135/)
- **SonarQube / SonarSource** `S1134` — تتبع استخدام وسوم "FIXME" (https://rules.sonarsource.com/javascript/RSPEC-1134/)