في هذا الدرس 6تصفّح المواضيع
تُمثل التعليقات البرمجية (Comments) ملاحظات توضيحية موجهة للمطورين البشر لشرح سبب اتخاذ قرار برمجي أو معادلة معينة داخل الملف؛ ويتخطاها المحلل اللغوي لمحرك JavaScript تماماً فلا تُنفذ ولا تؤثر على منطق البرنامج.
توفّر التعليقات الواضحة ساعات طويلة من الحيرة عندما تعود لمراجعة مشروعك بعد أشهر أو حين يعمل معك فريق مشترك على نفس الملف.
يبدأ التعليق أحادي السطر بشرطتين مائلتين متلاصقتين (//)؛ فيتجاهل محرك JavaScript كل حرف يأتي بعدهما حتى نهاية ذلك السطر فقط، سواء كُتب التعليق في سطر مستقل أعلى الأمر أو في نهاية السطر البرمجي نفسه.
// Display net invoice after 15 USD discount
document.getElementById('net-box').textContent = 200 - 15; // Outputs 185تبدأ التعليقات متعددة الأسطر بالرمز /* وتنتهي بالرمز */، فيتخطى المحرك جميع الأسطر المحصورة بينهما مهما طال عددها؛ وهو ما يجعلها مناسبة لكتابة توثيق موجز في مطلع الملف.
انتبه إلى أن تعليقات الكتل لا تقبل التداخل؛ فأول رمز إغلاق */ يصادفه المحرك ينهي التعليق فوراً ويعتبر ما بعده كوداً فعلياً.
/*
Shipping Calculator Rule:
Orders include a flat 12 USD express fee.
*/
document.getElementById('ship-box').textContent = 'Total with shipping: ' + (88 + 12);أثناء الفحص المحلي وعزل الأخطاء، يمكنك وضع // مؤقتاً في بداية سطر معين لإيقاف تشغيله ومقارنة النتيجة دون الاضطرار لحذفه؛ مع الحرص دائماً على تنظيف الأسطر المعطلة غير اللازمة قبل حفظ النسخة النهائية للمشروع.
القاعدة الذهبية في هندسة البرمجيات أن يشرح التعليق السبب والغاية (لماذا كُتب هذا الرقم أو الشرط؟) لا أن يعيد سرد الكود الواضح بذاته:
| جودة التعليق | المثال | التقييم الهندسي |
|---|---|---|
| تعليق حشوي مكرر | // Set text to Done | يُتجنب لأنه يكرر حرفياً ما يقوله السطر البرمجي بوضوح |
| تعليق يوضح السبب | // Limit summary to 160 chars for search snippet | ممتاز لأنه يوثق القيد الهندسي وراء اختيار الرقم 160 |
بخلاف لغات الخادم التي لا يغادر كودها المصدري جهاز الخادم، يتم تنزيل ملفات JavaScript الخاصة بالواجهة كاملةً إلى متصفح كل زائر؛ ويستطيع أي شخص يضغط F12 ويفتح تبويب Sources قراءة جميع التعليقات المكتوبة حرفاً بحرف.
لذلك يُحظر قطعياً وضع أي مفاتيح واجهات برمجية سرية (API Keys) أو بيانات دخول تجريبية أو روابط لوحات تحكم داخلية ضمن تعليقات الواجهة.
ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
اختتمت الفصل الأول بإتقان التعليقات أحادية السطر // ومتعددة الأسطر /* ... */، وتعطيل الأسطر مؤقتاً للفحص، وكتابة التعليقات الاحترافية وحماية ملفات الواجهة من تسريب الأسرار. الخطوة التالية: انتقل الآن إلى الفصل الثاني (تخزين البيانات) بدءاً من درس «تعريف المتغيرات بـ var» لتعلم حجز القيم في الذاكرة وإعادة استخدامها.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات3
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 Single-Line Comment (//) التعليق أحادي السطر (//)
- صيغة تعليق تبدأ بالشرطتين // وتجعل المحرك يتجاهل كل ما يتبعها حتى نهاية السطر نفسه.
- للمراجعة
- 02 Block Comment (/* ... */) تعليق الكتلة متعدد الأسطر
- تعليق يُحاط بـ /* و*/ ويمتد عبر عدة أسطر متتالية ولا يقبل التداخل داخل تعليق كتلة آخر.
- للمراجعة
- 03 Source Map (.js.map) ملف خريطة المصدر (.js.map)
- ملف يربط الكود المضغوط بالملفات المصدرية الأصلية وتعليقاتها لأغراض الفحص ويجب عدم كشفه علناً إن حوى تفاصيل داخلية.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات2
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 JSDoc JSDoc
- JavaScript Documentation Comments
- صيغة توثيق قياسية تبدأ بـ /** ... */ وتتيح لمحررات الأكواد عرض شرح وتلميحات ذكية فورية.
- للمراجعة
- 02 API API
- Application Programming Interface
- واجهة برمجة التطبيقات التي يُحظر تماماً وضع مفاتيحها السرية الخاصة داخل ملفات وتعليقات الواجهة الأمامية.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
قارن بين التبويب الأول والثاني في المحاكي التفاعلي لملاحظة أثر وضع // قبل السطر الثاني أثناء التجريب.
-
افتح مثال التعليق متعدد الأسطر في محرر الأكواد وعدّل الوصف المكتوب داخل /* ... */ دون التأثير على ناتج الجمع.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.