كيف تفهم مشروعًا برمجيًا قديمًا لم تشارك في كتابته؟

كيف تفهم مشروعًا برمجيًا قديمًا لم تشارك في كتابته؟

عالم البرمجة

مطورة تراجع مشروعًا برمجيًا قديمًا

قد تفتح مشروعًا عمره سنوات فتجد مئات الملفات، أسماء لا تعرف سببها، مكتبات قديمة، اختبارات متفرقة، ومسارات تنفيذ لا تظهر من النظرة الأولى.

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

 إلى كتلة أكبر في ذهنك بدل أن تجعله أوضح.

فهم مشروع قديم لا يبدأ بحفظ الشفرة، بل ببناء نموذج تدريجي لما يفعله النظام فعلًا: كيف يُشغَّل، من أين تبدأ الطلبات، أين تمر البيانات، ما المكونات التي تعتمد على غيرها، وما السلوك الذي يعتبره الفريق صحيحًا اليوم.

تعامل مع المشروع كمنظومة تحتاج إلى أدلة متقاطعة.

الشفرة دليل، والاختبارات دليل، والسجلات دليل، وتاريخ Git دليل، ووثائق الفريق وسياق العمل أدلة أخرى.

لا تجعل أي واحد منها مرجعًا مطلقًا قبل أن تقارنه بالبقية.

ابدأ بجعل المشروع قابلًا للتشغيل قبل محاولة فهمه كله

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

اقرأ تعليمات الإعداد، ملفات الاعتمادات، متغيرات البيئة المطلوبة، وأي ملفات حاويات أو أوامر تشغيل موجودة.

إذا فشل التشغيل، لا تتجاوز المشكلة سريعًا.

الخطأ نفسه يعلّمك ما الذي يعتمد عليه المشروع: قاعدة بيانات، خدمة رسائل، مخزن ملفات، مفتاح إعداد، أو إصدار محدد من أداة ما.

ولا تغيّر إعدادات الإنتاج لتجعل بيئتك تعمل.

الهدف أن تفهم طريقة تشغيل النظام من دون أن تخلق مسارًا جديدًا لا يستخدمه الفريق.

فرّق بين ما يحدث محليًا وما يحدث في البيئة الحقيقية

نجاح المشروع على جهازك لا يعني أن سلوكه يطابق الإنتاج بالكامل.

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

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

راقب الطلبات والأخطاء والقياسات ذات الصلة بالمسار الذي تدرسه، ولا تعدل بيانات حقيقية لمجرد التحقق من فرضية.

دوّن الفروق بين البيئات لأنها جزء من فهم النظام.

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

ارسم خريطة سطحية قبل النزول إلى التفاصيل

بعد التشغيل، لا تنتقل مباشرة إلى قراءة الدوال واحدة واحدة.

اكتب خريطة أولية: ما التطبيقات أو الخدمات الموجودة؟ أين نقطة الدخول؟ ما قاعدة البيانات؟ 

ما الأنظمة الخارجية؟ أين يوجد الجزء الأمامي، والخلفي، والمهام المجدولة، وطوابير الرسائل إن وجدت؟

لا تحاول أن تكون الخريطة كاملة.

يكفي أن توضح المكونات الكبرى واتجاهات الاتصال بينها.

إذا لم تعرف وظيفة مكون، ضع علامة سؤال بدل اختراع تفسير.

هذه الخريطة ستمنعك من قراءة ملف بمعزل عن موقعه في النظام، وستعطيك مكانًا تضيف

 إليه ما تتعلمه لاحقًا.

تتبع مسارًا واحدًا له معنى للمستخدم

اختر عملية يعرف الفريق قيمتها: تسجيل دخول، إنشاء طلب، إصدار فاتورة، رفع ملف، أو إرسال إشعار.

ابدأ من الحدث الذي يراه المستخدم وتتبع المسار حتى نهايته.

راقب نقطة استقبال الطلب، طبقة التحقق، قواعد العمل، الوصول إلى البيانات، والآثار الجانبية مثل الرسائل أو تحديثات الأنظمة الخارجية.

لا تحتاج في الجولة الأولى إلى فهم كل فرع شرطي.

المطلوب أن تجيب: ما الطريق الرئيسي الذي تسلكه هذه العملية؟ بعد ذلك يصبح كل ملف تقرؤه جزءًا من قصة معروفة بدل أن يكون قطعة معزولة.

استخدم المصحح والتتبعات لتختبر فرضياتك

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

استخدم نقاط التوقف أو أدوات التتبع في بيئة آمنة عندما تكون متاحة، وراقب القيم ومسار الاستدعاءات في العملية التي اخترتها.

في الأنظمة الموزعة، قد يكون التتبع أهم من المصحح المحلي لأن الطلب يمر عبر أكثر من خدمة.

التتبعات تساعدك على رؤية المسار بين المكونات، بينما السجلات تسجل أحداثًا وتفاصيل قد تفسر 

ما حدث داخل كل مرحلة.

لا تضف تسجيلًا كثيفًا إلى الإنتاج لمجرد الاستكشاف، ولا تسجل أسرارًا أو بيانات شخصية.

اجعل الرصد هادفًا ومحدودًا.

السجلات تخبرك بما حدث لا لماذا صُمم النظام هكذا

السجلات مفيدة لأنها تكشف السلوك الفعلي والأخطاء والأنماط المتكررة، لكنها ليست «ذاكرة كاملة للمشروع».

قد تكون ناقصة، أو صاخبة، أو غائبة في المسار الذي تبحث عنه.

ابدأ بالرسائل المرتبطة بالعملية التي تتتبعها، واربط الزمن ومعرف الطلب أو المعاملة إن كان النظام 

يوفر ذلك.

ابحث عن نقطة التحول بين السلوك المتوقع والسلوك غير المتوقع.

وإذا رأيت استعلامًا متكررًا أو خطأ شائعًا، لا تستنتج فورًا أنه أصل المشكلة.

سجّل الملاحظة ثم أثبتها بقياس أو تتبع إضافي.

الاختبارات عقود سلوكية مفيدة لكنها ليست حقيقة مطلقة

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

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

اقرأ ايضا : لماذا يظهر خطأ جديد بعد إصلاح خطأ برمجي؟

وقد يفشل اختبار لأن البيئة ناقصة، أو لأن الاختبار قديم، أو لأن سلوكًا تغير عمدًا.

لذلك لا تفسر كل فشل باعتباره عيبًا في الشفرة الحالية.

اقرأ أسماء الاختبارات والمدخلات والتوقعات، ثم قارنها بالوثائق والسلوك الفعلي وأصحاب المعرفة في الفريق.

عندما لا توجد اختبارات ثبّت السلوك قبل أن تغيّره

إذا كان الجزء الذي ستلمسه بلا تغطية كافية، اكتب اختبارات توصيف صغيرة حول السلوك الذي تعتمد

 عليه المهمة.

هدفها الأول هو تسجيل ما يفعله النظام الآن في الحالات المهمة، لا إعلان أن كل هذا السلوك صحيح.

اختر مدخلات واقعية، وحالات حافة معروفة، وأخطاء سبق أن حدثت إن أمكن.

ثم أضف توقعات تفشل إذا تغير السلوك الذي تريد حمايته دون قصد.

هذه الشبكة لا تمنحك ضمانًا كاملًا، لكنها تقلل مساحة المجهول قبل إعادة الهيكلة أو الإصلاح.

اقرأ تاريخ Git كسياق لا كحكم

استخدم git log لمعرفة متى تغير ملف أو وظيفة، وافتح التغييرات المرتبطة بالقرارات التي تبدو غريبة.

رسالة جيدة أو طلب دمج قد يشرح قيدًا تجاريًا أو حادثة أمنية أو انتقالًا معماريًا لم يعد ظاهرًا في الشفرة الحالية.

أما git blame فيوضح المراجعة والمؤلف اللذين عدّلا السطر أخيرًا؛ لا يعني بالضرورة أن هذا الشخص صمم الفكرة أو يملكها الآن.

إعادة التنسيق أو النقل قد تغير النتيجة أيضًا.

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

استخدم bisect عندما تبحث عن تغير محدد لا لفهم المشروع عمومًا

إذا كان لديك إصدار معروف يعمل وآخر يظهر فيه انحدار واضح، يمكن لأداة git bisect تضييق تاريخ التغييرات بالبحث الثنائي حتى تحدد التغيير الذي أدخل السلوك.

لكنها ليست أداة استكشاف عامة.

إذا لم تستطع تعريف حالة «كانت تعمل» وحالة «أصبحت لا تعمل» واختبارهما بصورة قابلة للتكرار،

 فلن تعطيك فهمًا معماريًا للمشروع.

ضع كل أداة في السؤال الذي صُممت للإجابة عنه بدل تشغيل أدوات كثيرة لأن المشروع يبدو معقدًا.

اسأل عن قواعد العمل قبل تحسين ما يبدو قبيحًا

قد ترى شرطًا متكررًا أو استثناءً غير أنيق وتظنه دينًا تقنيًا واضحًا.

أحيانًا يكون كذلك، وأحيانًا يكون أثرًا لقاعدة عمل نادرة لا تظهر في المسار الأساسي.

قبل حذف الاستثناء، اسأل: ما الحالة التي يحميها؟ هل توجد تذكرة قديمة أو اختبار أو مثال بيانات يشرحها؟ هل يعتمد عليها عميل أو تقرير أو تكامل خارجي؟

الكود القبيح ليس دائمًا كودًا زائدًا، والكود الأنيق ليس دائمًا صحيحًا.

الوظيفة أولًا، ثم الشكل.

افصل بين ما تعرفه وما تفترضه

أنشئ ملاحظة بسيطة بثلاث خانات: «مؤكد»، «مرجح»، و«غير معروف».

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

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

كما تساعدك عندما تسأل زميلًا؛ تستطيع أن تقول تحديدًا ما شاهدته وما الذي تحتاج إلى تفسيره.

كلما تحول عنصر من «غير معروف» إلى «مؤكد»، أصبحت تعديلاتك أقل اعتمادًا على التخمين.

استخدم الذكاء الاصطناعي كمساعد قراءة لا كمالك للحقيقة

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

هذا مفيد خصوصًا عندما تكون اللغة أو الإطار غير مألوفين لك.

لكن الشرح المولد قد يخطئ في النية أو يهمل اعتمادًا غير ظاهر أو يقترح تعديلًا يبدو صحيحًا وهو يكسر 

قيدًا تجاريًا.

لا تمنحه أسرارًا أو بيانات لا تسمح سياسة مؤسستك بمشاركتها.

اعتبر إجابته فرضية تحتاج إلى مراجعة وتشغيل واختبار، لا بديلًا عن أدلة المشروع نفسه.

إذا كان المستودع خاصًا أو يحتوي شفرات وبيانات حساسة، افحص أيضًا سياسة المؤسسة وإعدادات

 الأداة قبل إرسال السياق إلى أي خدمة خارجية.

القدرة على شرح الشفرة لا تمنح الأداة تلقائيًا حق الاطلاع عليها، وحماية الأسرار جزء من فهم المشروع 

بقدر ما هي جزء من تشغيله.

لا تبدأ بإعادة الكتابة من الصفر لأن الشفرة مزعجة

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

النظام القديم يحمل سلوكًا متراكمًا وتكاملات وحالات حافة قد لا تكون موثقة كلها.

قبل اقتراح إعادة كتابة واسعة، افهم تكلفة الاستمرار، ومخاطر التغيير، وحجم الاختبارات، ومسار الترحيل، وإمكان تشغيل القديم والجديد بالتوازي عند الحاجة.

في كثير من الحالات، تحسين جزء محدود حول مسار معروف يعطي الفريق معرفة أسرع ومخاطرة 

أقل من مشروع استبدال شامل يبدأ قبل فهم السلوك الحالي.

اجعل أول تعديل صغيرًا لكنه حقيقي

بعد أن تفهم مسارًا واحدًا وتملك طريقة لاختباره، اختر تغييرًا محدود النطاق: إصلاح خطأ معروف، 

تحسين رسالة، إزالة تكرار محلي، أو إضافة تحقق واضح.

لا تجعل أول مساهمة إعادة هيكلة عابرة لعشرات الملفات.

مرر التغيير عبر المسار الحقيقي للفريق: الاختبارات، المراجعة، البناء، والنشر أو بيئة الاختبار.

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

المهمة الصغيرة ليست هدفًا متواضعًا؛ إنها اختبار عملي لصحة النموذج الذي بنيته عن المشروع.

راقب ما يتغير كثيرًا لكن لا تسمه هشًا مباشرة

الملف الذي يتغير باستمرار يستحق الانتباه لأنه يقع غالبًا في منطقة نشطة من النظام، لكنه ليس بالضرورة سيئ التصميم.

قد يتغير لأنه يمثل جزءًا ينمو بسرعة أو قاعدة عمل كثيرة التعديل.

اجمع أكثر من إشارة قبل وصفه بأنه نقطة خطر: كثرة الأعطال، صعوبة الاختبار، تشابك الاعتمادات، 

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

الهدف من التاريخ هو توجيه انتباهك، لا إصدار حكم معماري آلي.

دوّن خريطة تسلمها لمن يأتي بعدك

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

لا تحول الملاحظات إلى موسوعة.

اكتب ما تم التحقق منه، وضع تاريخًا للمعلومات التي يمكن أن تتغير، واربطها بالمصدر عندما يكون

 ذلك مفيدًا.

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

استخدم مصفاة فهم المشروع قبل أي تعديل عميق

مرر الجزء الذي ستعدله عبر ستة أسئلة: التشغيل، هل أستطيع إعادة السلوك في بيئة آمنة؟ المسار، 

ما المكونات التي يمر بها؟ العقد، ما الاختبارات أو التوقعات التي تحميه؟

ثم التاريخ، لماذا تغير هذا الجزء سابقًا؟ الأثر، ما الأنظمة أو البيانات التي قد تتأثر؟ وأخيرًا التحقق،

 كيف سأعرف بعد التعديل أن السلوك المطلوب بقي صحيحًا؟

إذا بقيت إجابات أساسية مجهولة، فهذا ليس سببًا لعدم العمل؛ هو إشارة إلى أن خطوتك التالية 

يجب أن تكون تقليل المجهول قبل توسيع التغيير.

لا تحتاج إلى فهم كل المشروع كي تبدأ العمل بأمان

لن تصل غالبًا إلى لحظة تقول فيها إنك فهمت كل سطر وكل قرار.

المشاريع الحية أكبر من ذاكرة شخص واحد، وبعض التفاصيل لا تصبح مهمة إلا عندما تصل إليها مهمة حقيقية.

هدفك هو بناء فهم كافٍ للمنطقة التي ستتغير، مع معرفة حدود ما لا تعرفه.

اقرأ ايضا : كيف تكتب اختبارات برمجية تكشف الأعطال مبكرًا؟

شغّل النظام، ارسم خريطته الكبرى، تتبع عملية واحدة، قارن الشفرة بالاختبارات والتتبعات والتاريخ، 

ثم نفذ تعديلًا صغيرًا يمكن التحقق منه.

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

وكل تعديل موثق ومختبر يجعل السؤال التالي أسهل عليك وعلى من يأتي بعدك.