كان كودنا لغزاً: كيف أنقذتنا تعليقات ‘لماذا’ من جحيم الهندسة العكسية لشيفراتنا؟

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

كنا نشتغل على نظام معقد لمعالجة المدفوعات، وكان في عنا شاب “شغيل” وذكي اسمه سامر. في ليلة من الليالي، وهو يحل مشكلة مستعصية تتعلق بحساب العمولات المتغيرة بناءً على شروط غريبة من قسم المبيعات، طلع بحل “عبقري”. كتب دالة (function) مليئة بالعمليات الرياضية والمنطقية، واستخدم فيها تقنية برمجية ما حدا فينا كان متعود عليها كتير. وقتها، الكود اشتغل زي الحلاوة، والمشكلة انحلت، وكلنا صفقنا لسامر وقلنا له “كفّو يا وحش!”.

مرت الأسابيع، يمكن شهر أو شهرين. فجأة، وصلتنا تذكرة (ticket) من الدعم الفني تقول إن في خطأ في حساب العمولات لبعض الحالات الجديدة. طبعاً، أول إشي خطر ببالنا هو “دالة سامر العبقرية”. فتحنا الكود… وهنا كانت الصدمة. سامر نفسه كان في إجازة، ونحنا واقفين قدام الكود زي اللي واقف قدام شيفرة إنيجما في الحرب العالمية. كلنا بنعرف شو بيعمل الكود (ماذا)، لأنه بيطلع ناتج في النهاية، لكن ولا واحد فينا، وأنا أولكم، كان فاهم لماذا اختار سامر هاي الطريقة بالذات. ليش هاد الرقم بالذات؟ ليش استخدم `bit-wise shift` بدل الضرب؟ ليش قلب الشرط المنطقي بهالطريقة؟

قضينا يومين كاملين، مش بنكتب كود جديد، بل بنعمل هندسة عكسية للكود تبعنا! يومين ضاعوا من عمر المشروع، والضغط زاد، والقهوة صارت ما تعمل مفعول. ومن يومها، تغيرت نظرتنا للتعليقات البرمجية من “إشي ثانوي للمبتدئين” إلى “طوق نجاة للمحترفين”.

الفرق القاتل: تعليقات “ماذا” مقابل تعليقات “لماذا”

المشكلة اللي وقعنا فيها هي الاعتقاد الخاطئ بأن التعليقات وجدت لشرح “ماذا” يفعله الكود. وهذا أكبر فخ ممكن يقع فيه المبرمج.

النوع الأول: تعليقات “ماذا” (التي لا فائدة منها)

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

شوف هالمثال السيء:

// Define a variable 'x' and assign it the value 5
let x = 5;

// Loop from 0 to 10
for (let i = 0; i < 10; i++) {
    // Print the value of i
    console.log(i);
}

هذا الكلام، زي ما بنقول عنا، “زي عدمه”. أي مبرمج بيعرف يقرأ الكود ما بيحتاج حدا يشرح له إن `x = 5` بتعني إسناد القيمة 5 للمتغير x. هذا النوع من التعليقات بيعمل الكود أطول وأصعب في القراءة، وبيصير عبء في الصيانة لأنه لو غيرت الكود، لازم تتذكر تغير التعليق.

نصيحة أبو عمر: إذا شعرت أنك بحاجة لكتابة تعليق يشرح “ماذا” يفعله سطر واحد من الكود، فالأغلب أن المشكلة ليست في غياب التعليق، بل في الكود نفسه. حاول إعادة كتابة الكود ليصبح أوضح (مثلاً، عبر استخدام أسماء متغيرات ودوال معبرة).

النوع الثاني: تعليقات “لماذا” (المنقذة للحياة)

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

• لماذا تم اتخاذ هذا القرار الهندسي بالذات؟
• ما هي متطلبات العمل (Business Logic) الغريبة التي أدت إلى هذا الكود المعقد؟
• هل هذا حل مؤقت لمشكلة في مكتبة خارجية؟
• لماذا لم نستخدم الحل الأكثر شيوعاً أو وضوحاً؟

لنعد لمثال “دالة سامر العبقرية”. تخيل لو كان سامر قد ترك تعليقاً بسيطاً مثل هذا:

// The client requires a special commission calculation for 'VIP' users from the EU region
// during the Q4 promotion (ends Jan 1st, 2023).
// Standard multiplication was causing floating point precision errors with large transaction volumes,
// so we are using a bitwise shift here as a faster and more precise workaround for integer multiplication by 2.
// This is a known issue in library XYZ v1.2. See ticket #4321 for more context.
const commission = (baseAmount << 1) + specialBonus;

شايفين الفرق؟ هذا التعليق كان سيوفر علينا يومين من العذاب. في بضعة أسطر، فهمنا:

1. السبب التجاري: عمولة خاصة لعملاء VIP في أوروبا خلال فترة محددة.
2. السبب التقني: تجنب مشاكل الفاصلة العائمة (floating point) في عمليات الضرب القياسية.
3. الحل البديل: استخدام الإزاحة 位ية (bitwise shift) كبديل أسرع وأدق لعملية الضرب في 2.
4. السياق الخارجي: الإشارة إلى مشكلة معروفة في مكتبة معينة ورقم تذكرة للمزيد من التفاصيل.

هذا التعليق ليس ضجيجاً، بل هو جزء لا يتجزأ من توثيق الكود. هو رسالة من “أنا الماضي” إلى “أنا المستقبل” أو إلى أي زميل آخر. هو الخريطة التي تركتها وراءك في غابة الكود المعقد.

نصائح أبو عمر الذهبية لكتابة تعليقات “إشي مرتب”

من خبرتي على مدار السنين، جمعت لكم كم نصيحة عملية أتمنى أن تفيدكم:

1. اكتب التعليق وكأنك تشرح لزميلك الجديد

تخيل أن هناك مبرمجاً جديداً سينضم للفريق غداً، ومهمته الأولى هي فهم الكود الذي كتبته اليوم. ماذا كنت ستقول له لتشرح هذا الجزء المعقد؟ اكتب ذلك بالضبط. هذه العقلية ستجبرك على التركيز على “لماذا”.

2. وثّق “الاختراقات” والحلول غير التقليدية

أحياناً، نضطر لكتابة كود “قبيح” أو غير مباشر لحل مشكلة معينة (workaround). هذا هو المكان المثالي للتعليقات. اشرح لماذا كان هذا الحل ضرورياً وما هي المشكلة الأصلية التي يحلها.

// HACK: The third-party API sometimes returns a status of "succes" (with one 's') instead of "success".
// This condition handles both cases until they fix their typo.
if (response.status === "success" || response.status === "succes") {
    // ... process data
}

3. استخدم التعليقات لتحديد الديون التقنية (TODO, FIXME)

أحياناً لا يكون لديك الوقت الكافي لكتابة الحل الأمثل. لا بأس، ولكن اترك علامة لك وللفريق. استخدم كلمات مفتاحية مثل `TODO` أو `FIXME` التي يمكن لأدوات التطوير (IDEs) أن تتعرف عليها وتجمعها لك في قائمة واحدة.

// TODO: This is a temporary solution. We should refactor this to use the new caching service
// once it's deployed in the next sprint.
function getLegacyUserData(userId) {
    // ...
}

// FIXME: This algorithm has a complexity of O(n^2). It works for now, but will be slow
// with more than 1000 items. Needs optimization.
function calculateSimilarities(items) {
    // ...
}

4. الكود الجيد يغني عن التعليقات، لكنه لا يلغيها

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

الخلاصة: تعليق اليوم هو طوق نجاة الغد lifeboat

يا جماعة، الكود البرمجي نكتبه مرة، ولكننا نقرأه عشرات المرات (نحن وزملاؤنا). التعليقات ليست مجرد زينة أو مضيعة للوقت، بل هي استثمار حقيقي في مستقبل المشروع وفي صحتك النفسية وصحة فريقك. هي الجسر الذي يربط بين لحظة كتابة الكود ولحظة محاولة فهمه بعد ستة أشهر.

لا تكن مثلنا في تلك القصة، ولا تترك “أنت المستقبلي” عالقاً في جحيم الهندسة العكسية لكود كتبته أنت بنفسك. خذ دقيقة إضافية، واكتب تعليقاً يشرح “لماذا”. صدقني، “أنت المستقبلي” سيشكرك كثيراً. 😉

ودمتم سالمين مبرمجين! 👋