دليل تعلم جافاسكربت التعليقات في جافاسكربت

كما نعلم من جزء بنية الشيفرة البرمجية، يمكن ان تكون التعليقات ذات سطر واحد: وتبدأ ب // أو متعددة الأسطر: /* ... */.

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

التعليقات السيئة

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

// ستقوم هذه الشيفرة البرمجية بهذا الأمر (...) وذلك الأمر (...)
// وربما أشياء أخرى
very;
complex;
code;

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

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

طريقة: أخرج الدوال

أحيانا، يكون استبدال جزء من الشيفرة البرمجية أمرًا مهمًا كما يلي:

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    // check if i is a prime number
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue nextPrime;
    }

    alert(i);
  }
}

البديل الأفضل هو إخراج دالة isPrime:

function showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) continue;

    alert(i);
  }
}

function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}

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

طريقة: أنشئ دوالًا

إن كان هناك شيفرة برمجية طويلة كما يلي:

// here we add whiskey
for(let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// here we add juice
for(let t = 0; t < 3; t++) {
  let tomato = getTomato();
  examine(tomato);
  let juice = press(tomato);
  add(juice, glass);
}

// ...

فيُفضل إخراجه إلى دالة كما يلي:

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
  for(let i = 0; i < 10; i++) {
    let drop = getWhiskey();
    //...
  }
}

function addJuice(container) {
  for(let t = 0; t < 3; t++) {
    let tomato = getTomato();
    //...
  }
}

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

في الواقع لا يمكننا تجنب التعليقات التوضيحية. فهناك بعض الخوارزميات المعقدة وأدوات التعديل والتحسين الذكية (smart tweaks) للشيفرة البرمجية. لكن يجب أن نحاول أن نجعل الشيفرة البرمجية سهلا ويشرح نفسه.

التعليقات الجيدة

إن كانت التعليقات التوضيحية سيئة، فأي التعليقات هو الجيد؟

وصف الهيكلة

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

توثيق مُعامِلات الدوال واستخدامها

يوجد تركيب خاص بالجمل البرمجية يُسمَّى JSDoc لتوثيق الدوال: استخدامها، مُعامِلاتها، والقيم التي تُرجِعُها.

إليك المثال التالي:

/**
 * Returns x raised to the n-th power.
 *
 * @param {number} x The number to raise.
 * @param {number} n The power, must be a natural number.
 * @return {number} x raised to the n-th power.
 */
function pow(x, n) {
  ...
}

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

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

يوجد أيضا بعض الأدوات مثل JSDoc 3 والتي يمكنها توليد توثيق HTML من هذه التعليقات. للمزيد من المعلومات حول JSDoc اقرأ هنا http://usejsdoc.org/.

لم تم حل هذه المهمة بهذه الطريقة؟

ما هو مكتوب هو مهم، لكن قد يكون ما هو غير مكتوب أكثر أهمية لفهم ما يجري. لا تستطيع الشيفرة البرمجية الإجابة عن السؤال "لم تم حل هذه المهمة بهذه الطريقة؟".

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

بدون تعليقات توضح السبب يمكن حدوث التالي:

1. ستفتح الشيفرة البرمجية المكتوبة منذ وقت طويل (أنت أو أي شخص آخر) وسترى أنها "غير مناسبة".
2. ستفكر: "كم كنت غبيا حينها، وكم أنا ذكي الآن"، ثم ستُعيد كتابة الشيفرة البرمجية باستخدام البديل الذي تراه أكثر صحة وملائمة.
3. فكرة إعادة الكتابة تكون سهلة، لكن عند القيام بها تكتشف أن الحل "الأمثل" لا يتناسب مع الغرض المطلوب. حينها قد تتذكر السبب لأنك جربت الأمر ذاته مسبقا بالفعل ولم يفلح. ثم ستعود إلى الخيار السابق لكن بعد ضياع الوقت.

التعليقات التي توضح سبب استخدام طريقة ما هي مهمة جدا. فهي تساعد على الاستمرار بالتطوير مباشرة.

أي ميزات غير ملحوظة في الشيفرة البرمجية ومكان استخدامها

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

الخلاصة

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

علِّق ما يلي:

• الهيكلة العامة، النظرة عالية المستوى.
• استخدام الدوال.
• الحلول المهمة، خاصة تلك الغير ملحوظة مباشرة.

تجنب التعليقات:

• التي تشرح آلية عمل الشيفرة البرمجية والغرض منها.
• ضع مثل هذه التعليقات عندما يكون من المستحيل جعل الشيفرة البرمجية سهلة القراءة وتصف نفسها وتحتاج لتوضيح فقط

تستخدم التعليقات أيضا للأدوات التي تقوم بالتوثيق تلقائيا مثل JSDoc3: تقرأ هذه الأدوات التعليقات وتولِّد ملفات HTML أو بأي صيغة أخرى.

ترجمة -وبتصرف- للفصل Comments من كتاب The JavaScript Language

اقرأ أيضًا

• المقال التالي: شيفرة النينجا البرمجية
• المقال السابق: نمط كتابة الشيفرة