كما نعلم من الفصل بنية الكود، يمكن أن تكون التعليقات ذات سطر واحد: تبدأ بـ // ومتعددة الأسطر: /* ... */ .
نستخدمها عادةً لوصف كيفية عمل الكود ولماذا.
للوهلة الأولى، قد يكون التعليق واضحًا، لكن المبتدئين في البرمجة غالبًا ما يستخدمونه بشكل خاطئ.
يميل المبتدئون إلى استخدام التعليقات لشرح "ما يحدث في الكود". مثله:
// هذا الكود سيفعل هذا الشيء (...) وهذا الشيء (...) // ... ومن يعرف ماذا أيضًا ... جداً؛ معقد؛ شفرة؛
ولكن في الكود الجيد، يجب أن يكون مقدار هذه التعليقات "التوضيحية" في حده الأدنى. على محمل الجد، يجب أن يكون الكود سهل الفهم بدونها.
هناك قاعدة رائعة حول ذلك: "إذا كانت التعليمات البرمجية غير واضحة لدرجة أنها تتطلب تعليقًا، فربما يجب إعادة كتابتها بدلاً من ذلك".
في بعض الأحيان يكون من المفيد استبدال جزء من التعليمات البرمجية بوظيفة، كما هو الحال هنا:
وظيفة showPrimes (ن) {
نكست برايم:
لـ (دع i = 2; i < n; i++) {
// تحقق مما إذا كنت عددًا أوليًا
لـ (دع j = 2; j < i; j++) {
إذا (i % j == 0) تابع nextPrime؛
}
تنبيه (ط)؛
}
} البديل الأفضل، مع الدالة المأخذ عليها isPrime :
وظيفة showPrimes (ن) {
لـ (دع i = 2; i < n; i++) {
إذا استمر (!isPrime(i)) ؛
تنبيه (ط)؛
}
}
الدالة هي برايم (ن) {
لـ (دع i = 2; i < n; i++) {
إذا (n % i == 0) أرجع خطأ؛
}
عودة صحيحة؛
}الآن يمكننا فهم الكود بسهولة. الوظيفة نفسها تصبح التعليق. يسمى هذا الكود بالوصف الذاتي .
وإذا كان لدينا "ورقة رموز" طويلة مثل هذا:
// هنا نضيف الويسكي
من أجل (دع i = 0؛ i < 10؛ i++) {
Let drop = getWhiskey();
رائحة (قطرة) ؛
إضافة (قطرة، زجاج)؛
}
// هنا نضيف العصير
ل(دع ر = 0؛ ر < 3؛ ر ++) {
دع الطماطم = getTomato();
فحص(طماطم);
دع العصير = اضغط على (الطماطم) ؛
إضافة (عصير، زجاج)؛
}
// ...بعد ذلك قد يكون من الأفضل إعادة هيكلته إلى وظائف مثل:
addWhisky(glass);
addJuice(glass);
وظيفة إضافة ويسكي (حاوية) {
من أجل (دع i = 0؛ i < 10؛ i++) {
Let drop = getWhiskey();
//...
}
}
وظيفة addJuice(حاوية) {
ل(دع ر = 0؛ ر < 3؛ ر ++) {
دع الطماطم = getTomato();
//...
}
}مرة أخرى، الوظائف نفسها تخبرنا بما يحدث. لا يوجد شيء للتعليق. وأيضًا بنية الكود تكون أفضل عند التقسيم. من الواضح ما تفعله كل وظيفة، وما الذي تتطلبه وما الذي تُرجعه.
في الواقع، لا يمكننا تجنب التعليقات "التفسيرية" تمامًا. هناك خوارزميات معقدة. وهناك "تعديلات" ذكية لأغراض التحسين. لكن بشكل عام يجب أن نحاول إبقاء الكود بسيطًا ووصفيًا ذاتيًا.
لذلك، التعليقات التوضيحية عادة ما تكون سيئة. أي التعليقات جيدة؟
وصف الهندسة المعمارية
قدم نظرة عامة عالية المستوى على المكونات، وكيفية تفاعلها، وما هو تدفق التحكم في المواقف المختلفة... باختصار - نظرة عامة على الكود. هناك لغة UML خاصة لإنشاء مخططات معمارية عالية المستوى تشرح الكود. بالتأكيد تستحق الدراسة.
معلمات وظيفة الوثيقة واستخدامها
هناك صيغة JSDoc خاصة لتوثيق دالة: الاستخدام، المعلمات، القيمة المعادة.
على سبيل المثال:
/**
* إرجاع x مرفوعًا إلى القوة n.
*
* @param {number} x الرقم المطلوب رفعه.
* @param {number} n يجب أن تكون القوة عددًا طبيعيًا.
* @return {number} x مرفوع للأس n.
*/
وظيفة الأسرى (س، ن) {
...
}تسمح لنا مثل هذه التعليقات بفهم الغرض من الوظيفة واستخدامها بالطريقة الصحيحة دون النظر إلى الكود الخاص بها.
بالمناسبة، يمكن للعديد من المحررين مثل WebStorm فهمها أيضًا واستخدامها لتوفير الإكمال التلقائي وبعض عمليات التحقق التلقائي من التعليمات البرمجية.
هناك أيضًا أدوات مثل JSDoc 3 التي يمكنها إنشاء وثائق HTML من التعليقات. يمكنك قراءة المزيد من المعلومات حول JSDoc على https://jsdoc.app.
لماذا تم حل المهمة بهذه الطريقة؟
ما هو مكتوب هو المهم. لكن ما لم يُكتب قد يكون أكثر أهمية لفهم ما يحدث. لماذا تم حل المهمة بهذه الطريقة بالضبط؟ الكود لا يعطي إجابة.
إذا كانت هناك طرق عديدة لحل المهمة، فلماذا هذه الطريقة؟ خاصة عندما لا يكون الأمر الأكثر وضوحًا.
بدون هذه التعليقات من الممكن أن يحدث الوضع التالي:
أنت (أو زميلك) تفتح الكود المكتوب منذ بعض الوقت، وترى أنه "دون المستوى الأمثل".
تعتقد: "كم كنت غبيًا في ذلك الوقت، وكم أنا أكثر ذكاءً الآن"، وتعيد الكتابة باستخدام البديل "الأكثر وضوحًا وصحيحًا".
…كانت الرغبة في إعادة الكتابة جيدة. ولكن في هذه العملية ترى أن الحل "الأكثر وضوحًا" غير موجود بالفعل. حتى أنك تتذكر السبب بشكل خافت، لأنك جربته بالفعل منذ فترة طويلة. يمكنك العودة إلى المتغير الصحيح، ولكن تم إضاعة الوقت.
التعليقات التي تشرح الحل مهمة جدًا. أنها تساعد على مواصلة التطوير بالطريقة الصحيحة.
أي ميزات خفية من التعليمات البرمجية؟ أين يتم استخدامها؟
إذا كانت التعليمات البرمجية تحتوي على أي شيء دقيق وغير بديهي، فمن المؤكد أنها تستحق التعليق.
من العلامات المهمة للمطور الجيد هي التعليقات: وجودها وحتى غيابها.
تتيح لنا التعليقات الجيدة الحفاظ على الكود جيدًا والعودة إليه بعد تأخير واستخدامه بشكل أكثر فعالية.
التعليق على هذا:
الهندسة المعمارية الشاملة، وعرض رفيع المستوى.
استخدام الوظيفة.
حلول مهمة، خاصة عندما لا تكون واضحة على الفور.
تجنب التعليقات:
يوضح ذلك "كيف يعمل الكود" و"ماذا يفعل".
ضعها فقط إذا كان من المستحيل جعل الكود بسيطًا جدًا ووصفًا ذاتيًا بحيث لا يتطلب ذلك.
تُستخدم التعليقات أيضًا لأدوات التوثيق التلقائي مثل JSDoc3: حيث يقومون بقراءتها وإنشاء مستندات HTML (أو مستندات بتنسيق آخر).