التعليقات

كما نعلم من الفصل <info: structure> ، يمكن أن تكون التعليقات سطر واحد: بدءًا من // و multiline: / * ... * /.

نستخدمها عادةً لوصف كيف ولماذا يعمل الرمز.

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

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

يميل المبتدئون إلى استخدام التعليقات لشرح “ما يجري في الكود”. مثله:

// This code will do this thing (...) and that thing (...)
// ...and who knows what else...
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();
    //...
  }
}

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

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

تعليقات جيدة

لذا ، التعليقات التوضيحية عادة ما تكون سيئة. ما هي التعليقات الجيدة؟

وصف العمارة

تقديم نظرة عامة عالية المستوى على المكونات ، وكيفية تفاعلها ، وما هو تدفق التحكم في المواقف المختلفة … باختصار – رؤية عين الطائر للرمز. هناك لغة خاصة [UML] (http://wikipedia.org/wiki/Unified_Modeling_Language) لإنشاء مخططات معمارية عالية المستوى تشرح الكود. بالتأكيد تستحق الدراسة.

معلمات وظيفة الوثيقة واستخدامها

هناك بنية خاصة [JSDoc] (http://en.wikipedia.org/wiki/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) {
  ...
}

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

بالمناسبة ، يمكن للعديد من المحررين مثل [WebStorm] (https://www.jetbrains.com/webstorm/) فهمهم أيضًا واستخدامهم لتوفير الإكمال التلقائي وبعض التحقق التلقائي من التعليمات البرمجية.

أيضًا ، هناك أدوات مثل [JSDoc 3] (https://github.com/jsdoc3/jsdoc) يمكنها إنشاء وثائق HTML من التعليقات. يمكنك قراءة المزيد من المعلومات حول JSDoc على http://usejsdoc.org/.

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

ما هو مكتوب مهم. لكن ما هو * غير * مكتوب قد يكون أكثر أهمية لفهم ما يحدث. لماذا يتم حل المهمة بهذه الطريقة بالضبط؟ الكود لا يعطي إجابة.

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

بدون هذه التعليقات يكون الوضع التالي ممكناً:

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

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

أي ميزات خفية للكود؟ أين يتم استخدامها؟

إذا كان الرمز يحتوي على أي شيء خفي وغير بديهي ، فمن المؤكد أنه يستحق التعليق.

ملخص

من التعليقات الهامة لمطور جيد التعليقات: حضورهم وحتى غيابهم.

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

** تعليق هذا: **

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

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

• يخبر “كيف يعمل الرمز” و “ماذا يفعل”.
• ضعهم فقط إذا كان من المستحيل جعل الكود بسيطًا وصفيًا ذاتيًا بحيث لا يتطلبهم.

تُستخدم التعليقات أيضًا في أدوات التوثيق التلقائي مثل JSDoc3: فهم يقرؤونها وينشئون مستندات HTML (أو مستندات بتنسيق آخر).