أوامر برمجية دقيقة: توليد كود نظيف وفعّال

لماذا يهم هذا الفصل؟ المشكلة الحقيقية التي يحلّها

عندما تطلب من أداة ذكاء اصطناعي مثل ChatGPT أو Claude أو GitHub Copilot أن "اكتب لي دالة"، غالباً ما تحصل على كود يعمل في المختبر لكنه يفشل في مشروعك الحقيقي. السبب ليس ضعف الأداة، بل غموض طلبك. أنت لم تحدّد لغة البرمجة بدقة، لم تذكر إصدار المكتبة، لم توضّح شكل المدخلات والمخرجات، ولم تطلب معالجة الأخطاء. النتيجة: كود عام يحتاج إلى إعادة كتابة كاملة.

المحترفون لا يكتبون أوامر عامة. يكتبون أوامر دقيقة تشبه مواصفات فنية (Technical Specification). هذا الفصل يعلّمك كيف تحوّل طلبك من "اكتب دالة" إلى "اكتب دالة Python بإصدار 3.11 تستقبل قائمة أرقام صحيحة، وتعيد قاموساً يحتوي على المتوسط والوسيط والانحراف المعياري، مع معالجة حالة القائمة الفارغة برفع استثناء مخصص". الفرق بين الجملتين هو الفرق بين كود هاوي وكود يُنشر في إنتاج حقيقي.

المكونات الخمسة لأمر توليد كود احترافي

أي أمر لتوليد كود يجب أن يحتوي على خمسة عناصر أساسية. حذف أي عنصر يؤدي إلى مخرجات ناقصة:

• اللغة والإصدار: "Python 3.11" وليس "Python". الإصدارات تختلف في بناء الجمل والمكتبات المدمجة.
• الإطار أو المكتبة (Framework): هل تستخدم Django أم Flask أم FastAPI؟ هل تستخدم React أم Vue؟ تحديد الإطار يغيّر بنية الكود بالكامل.
• المدخلات والمخرجات (I/O): ما هو نوع البيانات الداخل؟ ما هو نوع البيانات الخارج؟ هل هي JSON؟ قائمة؟ ملف؟
• معالجة الأخطاء: ماذا يحدث عند إدخال غير صالح؟ هل نرفع استثناء؟ هل نعيد رسالة خطأ؟ هل نسجّل الخطأ في ملف؟
• القيود والافتراضات: هل الكود يجب أن يكون متوافقاً مع معايير PEP8؟ هل يجب أن يكون آمناً ضد هجمات SQL Injection؟ هل يجب أن يعمل مع بيانات ضخمة؟

مثال عملي مُفصّل: توليد دالة Python مع Docstring

لنأخذ مثالاً واقعياً. أنت تعمل على مشروع تحليل بيانات مالية، وتحتاج دالة تحسب العائد السنوي المركّب (CAGR) من قائمة من العوائد الشهرية. إليك الأمر الاحترافي:

اكتب دالة Python بإصدار 3.11 باسم calculate_cagr.

المتطلبات:
- المدخل: قائمة من الأرقام العشرية (float) تمثل العوائد الشهرية كنسب مئوية (مثال: 0.05 تعني 5%).
- المخرج: رقم عشري واحد يمثل العائد السنوي المركّب كنسبة مئوية.
- المعادلة: CAGR = ( (1 + متوسط العائد الشهري) ^ 12 ) - 1
- معالجة الأخطاء:
  * إذا كانت القائمة فارغة، ارفع ValueError مع رسالة "القائمة لا يمكن أن تكون فارغة".
  * إذا كان أي عنصر أقل من -1 (أي خسارة أكبر من 100%)، ارفع ValueError مع رسالة توضيحية.
- اكتب Docstring بصيغة Google Style تشرح المعاملات، قيمة الإرجاع، والاستثناءات المرفوعة.
- لا تستخدم أي مكتبات خارجية، فقط math.
- أضف مثال استخدام في نهاية الـ Docstring.

هذا الأمر يحدد كل شيء. الأداة ستعيد كوداً مثل هذا:

import math
from typing import List, Union

def calculate_cagr(monthly_returns: List[float]) -> float:
    """
    Calculates the Compound Annual Growth Rate (CAGR) from monthly returns.

    Args:
        monthly_returns: A list of floats representing monthly returns as
            percentages (e.g., 0.05 for 5%). Values must be greater than -1.

    Returns:
        The CAGR as a percentage (e.g., 0.60 for 60%).

    Raises:
        ValueError: If the list is empty or contains a value less than or equal to -1.

    Example:
        >>> calculate_cagr([0.01, 0.02, -0.005, 0.03])
        0.148...
    """
    if not monthly_returns:
        raise ValueError("القائمة لا يمكن أن تكون فارغة")

    for ret in monthly_returns:
        if ret <= -1.0:
            raise ValueError(f"العائد {ret} غير صالح: يجب أن يكون أكبر من -1")

    avg_monthly_return = sum(monthly_returns) / len(monthly_returns)
    cagr = (1 + avg_monthly_return) ** 12 - 1
    return cagr

لاحظ أن الكود الناتج يلتزم بكل القيود: يستخدم math فقط، يرفع الاستثناءات المحددة، يكتب Docstring بصيغة Google Style، ويضيف مثال استخدام. هذا هو الفرق بين أمر غامض وأمر احترافي.

تطبيق خطوة بخطوة: توليد REST API في Node.js

الآن لنطبّق المبادئ نفسها على مثال أكثر تعقيداً: توليد نقطة نهاية REST API في Node.js. لنفترض أنك تستخدم Express 4.18 وتريد نقطة نهاية لإدارة المستخدمين.

الخطوة 1: حدد السياق الكامل

اكتب أمراً يذكر: اللغة (JavaScript أو TypeScript)، إصدار Node.js (18 أو 20)، إطار العمل (Express)، قاعدة البيانات (MongoDB مع Mongoose أو PostgreSQL مع Prisma)، ونمط المصادقة (JWT أو Session).

الخطوة 2: حدد المسار والطريقة (Endpoint and Method)

قل بوضوح: "أنشئ نقطة نهاية POST /api/users التي تستقبل JSON بالحقول التالية: name (string, required), email (string, required, unique), password (string, required, min 8 characters)".

الخطوة 3: حدد سلوك النجاح والفشل

قل: "عند النجاح، أعد كود حالة 201 مع كائن JSON يحتوي على id و email فقط (لا تُرجع كلمة المرور). عند فشل التحقق من الصحة، أعد كود 400 مع رسالة خطأ مفصلة. عند وجود بريد إلكتروني مكرر، أعد كود 409 مع رسالة 'البريد الإلكتروني مستخدم بالفعل'."

الخطوة 4: اطلب معالجة الأخطاء العامة

أضف: "لفّ الكود في محاولة/قبض (try/catch) وأعد كود 500 مع رسالة خطأ عامة عند أي استثناء غير متوقع. لا تكشف تفاصيل الخطأ الداخلية للمستخدم."

الخطوة 5: اطلب تنسيق الكود

قل: "استخدم async/await بدلاً من الـ callbacks. استخدم ESLint مع قواعد Airbnb. أضف تعليقات JSDoc للدالة الرئيسية."

الأمر الكامل سيبدو هكذا:

اكتب نقطة نهاية REST API في Node.js 20 باستخدام Express 4.18 و Mongoose 8.

المسار: POST /api/users

المدخل (JSON):
{
  "name": "string (مطلوب، الحد الأقصى 50 حرفاً)",
  "email": "string (مطلوب، صيغة بريد صحيحة)",
  "password": "string (مطلوب، 8 أحرف على الأقل)"
}

المخرج عند النجاح (كود 201):
{
  "id": "string (ObjectId)",
  "email": "string"
}

معالجة الأخطاء:
- فشل التحقق من الصحة: كود 400 مع رسالة تصف الحقل الخاطئ.
- بريد إلكتروني مكرر: كود 409 مع رسالة "البريد الإلكتروني مستخدم بالفعل".
- أي خطأ آخر: كود 500 مع رسالة "خطأ داخلي في الخادم".

المتطلبات:
- استخدم async/await.
- استخدم دالة hashing لكلمة المرور (bcrypt).
- لا تُرجع كلمة المرور أو نسخة الهاش في الاستجابة.
- أضف تعليقات JSDoc للـ handler.
- استخدم ESLint مع قواعد Airbnb.

هذا الأمر ينتج كوداً جاهزاً للإنتاج. يمكنك نسخه مباشرة إلى مشروعك بعد تثبيت الحزم المطلوبة.

الأخطاء الشائعة عند كتابة أوامر توليد الكود

تمرين تطبيقي (أقل من 15 دقيقة)

اكتب أمراً (Prompt) لتوليد دالة في JavaScript (وليس TypeScript) تحسب المجموع التراكمي لمصفوفة من الأرقام. استخدم المكونات الخمسة التي تعلمتها:

• حدد إصدار JavaScript (ES2022).
• حدد المدخل: مصفوفة من الأرقام (قد تحتوي على أرقام سالبة).
• حدد المخرج: مصفوفة جديدة بنفس الطول، حيث كل عنصر هو مجموع العناصر من البداية حتى هذا الموضع.
• حدد معالجة الأخطاء: إذا كانت المصفوفة تحتوي على عنصر غير رقمي، ارفع TypeError.
• اطلب Docstring بصيغة JSDoc مع مثال استخدام.

طريقة التحقق الذاتي: بعد كتابة الأمر، نفّذه في أي أداة ذكاء اصطناعي. اختبر الكود الناتج في متصفحك (F12 ثم Console) أو في Node.js بالمدخلات التالية: [1, 2, 3, 4] يجب أن يعيد [1, 3, 6, 10]. اختبر أيضاً مع [-1, 0, 5] يجب أن يعيد [-1, -1, 4]. إذا نجح الكود في هاتين الحالتين، فقد كتبت أمراً احترافياً. إذا فشل، راجع أمرك: هل حددت نوع الخطأ؟ هل حددت سلوك الحالة الفارغة؟