شيفرتك البرمجية تصرخ ‘لماذا؟’: فن كتابة التعليقات التي تشرح النية وليس التنفيذ

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

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

الكود كان مليان تعليقات، بس يا ريتها ما كانت. كل تعليق كان بيشرح السطر اللي تحته بشكل حرفي. يعني جنب سطر x = x + 1; بتلاقي تعليق لطيف بيقول: // زيادة قيمة x بمقدار واحد. يا سلام! كثر الله خيرك، والله ما كنت عارف! قضيت ثلاثة أيام، نعم ثلاثة أيام كاملة، وأنا بحاول أفهم ليش في دالة معينة بترجع قيمة سالبة في حالة خاصة جداً. الكود كان شغال، بس ليش هيك؟ شو القصة؟ شو المنطق اللي خلى المبرمج الأول يكتبها بهالطريقة الغريبة؟

بعد حفر وتنقيب، اكتشفت إنه كان بيعالج حالة نادرة بتيجي من نظام قديم (legacy system) كان بيبعت أرقام سالبة للتعبير عن خطأ معين. المبرمج الأول عالجها، بس ما ترك وراه أي أثر أو تعليق يشرح “لماذا”. لو كان كاتب سطر واحد بس، زي // معالجة الأخطاء القادمة من نظام الفوترة القديم حيث السالب يعني فشل العملية، كان وفّر عليّ أيام من الصداع والقهوة الزايدة. هذيك اللحظة، أدركت أن التعليق البرمجي مش مجرد شرح، هو حوار مع المستقبل.

لماذا تصرخ شيفرتك “لماذا؟”

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

مثال على تعليق سيء (يشرح “ماذا”)

تخيل معي هذا الكود البسيط في لغة JavaScript:

// تعريف دالة تأخذ اسم المستخدم
function getUser(name) {
  // البحث في مصفوفة المستخدمين
  const user = users.find(u => u.name === name);
  // إرجاع المستخدم
  return user;
}

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

فن التعليقات: من “ماذا” إلى “لماذا”

التعليق الجيد هو اللي بيجاوب على سؤال “لماذا؟”. لماذا اخترت هذه الخوارزمية بالذات؟ لماذا يوجد هذا الشرط الغريب؟ ما هو السياق التجاري (Business context) وراء هذا الجزء من الكود؟

التعليقات التي تشرح “النية” (Intent)

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

لنأخذ مثالاً على تعبير نمطي (Regular Expression) قد يبدو معقداً:

// هذا التعبير النمطي يبدو معقداً، ولكنه ضروري للتعامل مع حالات خاصة
// في بيانات المستخدمين القديمة، حيث كان البعض يدخل أرقام هواتف
// مع مسافات أو أقواس أو حتى بدون رمز الدولة. هذا يضمن توحيدها جميعاً.
const phoneRegex = /^(?(d{3}))?[-. ]?(d{3})[-. ]?(d{4})$/;

function normalizePhoneNumber(phone) {
  return phone.replace(phoneRegex, '($1) $2-$3');
}

هنا، التعليق لا يشرح ماذا يفعل التعبير النمطي (لأن هذا يمكن البحث عنه)، بل يشرح لماذا نحتاج لهذا التعبير المعقد بالذات. هذا التعليق يمنح المبرمج الذي سيأتي بعدك سياقاً تاريخياً وقرارياً مهماً جداً.

التعليقات التي توثق القرارات (Decisions)

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

نصيحة أبو عمر: وثّق تضحياتك! إذا اخترت حلاً أسرع ولكنه أقل أناقة، اشرح السبب. زميلك المستقبلي سيشكرك لأنك منعته من “تحسين” الكود وإبطائه عن غير قصد.

function processLargeDataSet(data) {
  // تم استخدام حلقة for التقليدية بدلاً من forEach أو map عن قصد.
  // أظهرت الاختبارات على مجموعات البيانات الضخمة (أكثر من مليون عنصر)
  // أن حلقة for التقليدية أسرع بنسبة تصل إلى 50% في محرك V8.
  // التضحية بالقراءة السهلة هنا مبررة من أجل الأداء.
  for (let i = 0; i < data.length; i++) {
    // ... عملية معالجة معقدة
  }
}

التعليقات كـ “تحذيرات” (Warnings)

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

// تحذير: هذه الدالة تقوم بتعديل كائن الجلسة (Session) العام.
// لا تستدعيها إلا في بداية تحميل الصفحة. استدعاؤها في مكان آخر
// قد يؤدي إلى نتائج غير متوقعة في واجهة المستخدم.
function initializeSession() {
  // ...
}

متى يجب أن تصمت؟ الكود النظيف هو أفضل تعليق

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

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

• استخدم أسماء ذات معنى: بدلاً من let d;، اكتب let elapsedTimeInDays;.
• اكتب دوال قصيرة ومحددة: الدالة التي تقوم بعشرين شيئاً مختلفاً تحتاج إلى رواية لشرحها. قسّمها إلى دوال أصغر كل منها يقوم بشيء واحد فقط.

قارن بين هذين المثالين:

مثال سيء (يعتمد على التعليقات):

// التأكد من أن المستخدم فوق 18 عاماً
function check(user) {
  const d = new Date();
  const y = d.getFullYear();
  const by = new Date(user.birthDate).getFullYear();
  if (y - by > 18) {
    return true;
  } else {
    return false;
  }
}

مثال جيد (كود يشرح نفسه):

const LEGAL_AGE = 18;

function isUserOverLegalAge(user) {
  const birthYear = new Date(user.birthDate).getFullYear();
  const currentYear = new Date().getFullYear();
  const age = currentYear - birthYear;
  return age >= LEGAL_AGE;
}

لاحظ كيف أن المثال الثاني لا يحتاج إلى أي تعليق. أسماء المتغيرات والدوال والثوابت تجعل الكود مقروءاً مثل جملة إنجليزية (أو عربية!).

الخلاصة: اجعل تعليقاتك همسة حكيمة وليست صرخة مزعجة

في النهاية يا صديقي، تذكر أنك تكتب الكود مرة واحدة، ولكنه يُقرأ مرات ومرات (منك ومن فريقك ومن “أبو عمر” المسكين الذي سيأتي بعدك بسنتين). التعليقات ليست واجباً مدرسياً، بل هي جسر تواصل تبنيه مع المستقبل.

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