لماذا يجب أن تكون التعليقات فهارس؟

التعليقات تُكتب للبشر.

// GetUser retrieves a user by ID from the database.
func GetUser(id string) (*User, error) {

هذا التعليق مفيد عندما يقرأه إنسان. لكن عندما تقرأه الآلة لا تعرف شيئاً. لا تعرف ما إذا كان “retrieves” يعني Read أم Search. لا تعرف ما هو الكيان الذي يمثّله “user”. لا تعرف ما إذا كانت هذه الدالة تتبع نمط Service أم نمط Repository.

لأن التعليق سرد.

عندما يبلغ عدد الدوال 10,000

عندما يكون عدد الدوال 10، لا مشكلة. يستطيع الإنسان قراءتها جميعاً.

عندما يبلغ عدد الدوال 10,000 يختلف الأمر. عندما تطلب “أرني جميع الدوال المتعلقة بالدفع”، لا يستطيع الإنسان إيجادها ولا الآلة. يُعثر فقط على تلك التي تحتوي أسماؤها على “payment”. إذا لم يكن الاسم كذلك، تضيع.

نفس الأمر ينطبق عندما يعدّل وكيل ذكاء اصطناعي الكود. عندما تطلب من Claude Code “أصلح معالجة خطأ PaymentFailed”، يعيد الوكيل قراءة الكود بأكمله. في كل مرة. يستوعب 10,000 دالة من الصفر في كل مرة. يقرأ اليوم نفس الكود الذي قرأه بالأمس. حتى مع وجود التعليقات لا يتغير شيء. لأن التعليقات سرد مكتوب للبشر. لكي تستخلص الآلة المعنى من السرد تحتاج إلى استدلال. وهذا مكلف.

ماذا لو كان التعليق فهرساً

// CreateOrder processes a new order creation.
//
// # Pattern: Service, Transactional
// # Entity: Order
// # Action: Create
// # Input: CreateOrderRequest {items:[]Item, userID:string}
//          pre: items>0 userID!=''
// # Output: *OrderResponse, error
//          errs: [StockInsufficient, PaymentFailed]
// # Deps: InventorySvc, PaymentGateway
func (s *OrderService) CreateOrder(req CreateOrderRequest) (*OrderResponse, error) {

هذا التعليق يستطيع الإنسان قراءته، وتستطيع الآلة قراءته أيضاً.

“جميع الدوال التي تتبع نمط Service” ← البحث في حقل Pattern. فوراً. “جميع الدوال المتعلقة بكيان Order” ← البحث في حقل Entity. فوراً. “الدوال التي تُطلق PaymentFailed” ← البحث في حقل errs. فوراً.

المسح الشامل يتحول إلى بحث بالفهرس. O(n) يصبح O(1).

لا حاجة لأن يكتبه الإنسان

ليست هناك حاجة لأن يكتب الإنسان هذا الفهرس.

عند تعديل الكود يُكتشف تلقائياً. مراقبة الملفات. تُفصل الدالة المعدّلة بواسطة AST. عملية آلية. يُمرَّر جسم الدالة إلى نموذج لغوي صغير. “حدّد نمط هذه الدالة وكيانها وإجراءها.” تُدرج النتيجة بتنسيق محدد. عملية آلية.

الإنسان لا يفعل شيئاً. يكتب الكود فقط. الفهرس يُضاف تلقائياً.

في خط الأنابيب بأكمله، النقطة الوحيدة التي يتدخل فيها النموذج اللغوي هي تحديد معنى الدالة. كل شيء آخر كود حتمي.

من الاستدلال إلى القواعد

نذهب خطوة أبعد.

عندما يضع النموذج اللغوي الصغير نفس الفهرس لنفس النمط بشكل متكرر — يُكتشف هذا التكرار. إذا تكرر “Service suffix مع receiver method يعني Pattern:Service” مئة مرة، يتحول إلى قاعدة ثابتة. بعدها لا يُستدعى النموذج اللغوي. القاعدة تتولى الأمر.

استدعاءات النموذج اللغوي تتناقص تدريجياً. القواعد تتزايد تدريجياً. التكلفة تتقارب نحو الصفر.

التعليقات تتحول من سرد إلى فهرس، والفهرس يتحول من يدوي إلى تلقائي، والتلقائي يتحول من استدلال إلى قواعد.

لماذا هذا ممكن: أنماط التصميم ككتاب شفرات

هناك سبب يجعل هذا ممكناً.

البرمجة تملك بالفعل مفردات دلالية موحّدة. إنها أنماط التصميم.

Singleton، Factory، Observer، MVC، Service. منذ أن جمعت GoF ثلاثة وعشرين نمطاً عام 1994، قضت صناعة البرمجيات ثلاثين عاماً في توسيع وتوحيد هذه المفردات.

أنماط GoF الثلاث والعشرون. Enterprise Application Patterns. Cloud Design Patterns. Go Concurrency Patterns. كلها مُنظّمة بالفعل.

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

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

اللغة الطبيعية لا تملك هذا. كلمة “عظيم” لها تعريف في القاموس لكن كل شخص يستخدمها بشكل مختلف. في الكود، لا يُستخدم Service بشكل مختلف من شخص لآخر.

لماذا الكود هو أسهل مجال

خط أنابيب السياق في GEUL — التوضيح، الفهرسة، التحقق، التصفية، التماسك، الاستكشاف — تطبيقه على اللغة الطبيعية صعب. تطبيقه على الكود سهل.

التوضيح: اللغة الطبيعية غامضة. الكود إذا مرّ عبر المترجم فالمعنى محسوم. الفهرسة: كيانات اللغة الطبيعية تحتاج سياقاً لفهمها. كيانات الكود قد حلّلها AST مسبقاً. التحقق: صحة اللغة الطبيعية لا يمكن تعريفها. صحة الكود يحكم بها المترجم. التصفية: ارتباط اللغة الطبيعية يحتاج نموذجاً لغوياً للحكم. ارتباط الكود يُحدّد آلياً عبر رسم بياني للاستدعاءات. التماسك: تناقضات اللغة الطبيعية تحتاج استدلالاً لاكتشافها. تناقضات الكود يكشفها نظام الأنواع والاختبارات. الاستكشاف: المعرفة في اللغة الطبيعية مسطحة. الكود يملك بالفعل بنية هرمية: حزمة → ملف → نوع → طريقة.

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

خلاصة

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

الكود يملك بالفعل معنى، ويملك بالفعل بنية، ويملك بالفعل مفردات. ما ينقصه هو الفهرس فقط. يكفي أن يصبح التعليق ذلك الفهرس.