نوعان من التعليقات في جافا سكريبت
توفّر لغة جافا سكريبت طريقتين لكتابة التعليقات. الطريقة الأولى هي التعليق أحادي السطر، ويبدأ بالرمز // ويمتد حتى نهاية السطر:
التعليقات المتعددة الأسطر في جافا سكريبت تبدأ بـ /* وتنتهي عند أول */ يظهر بعدها، ويمكن أن تمتد على عدد غير محدود من الأسطر حسب حاجتك:
كلا الشكلين يتم تجاهلهما تمامًا من قِبل محرك جافا سكريبت. وجودهما مخصص للبشر فقط — لك، ولزملائك في الفريق، ولنفسك عندما تعود لقراءة هذا الكود بعد ستة أشهر.
التعليقات أحادية السطر في جافا سكريبت
العلامة // هي الأكثر استخدامًا في جافا سكريبت. كل ما يأتي بعد // في نفس السطر يُعتبر تعليقًا، أما السطر الذي يليه فيعود ليكون كودًا عاديًا:
التعليقات في نهاية السطر (بعد الجملة البرمجية) مناسبة للملاحظات القصيرة. أما لو طالت الملاحظة لدرجة أنها تلتف على سطر جديد، فالأفضل نقلها إلى سطر مستقل فوق الكود؛ لأن التعليقات الطويلة في نهاية السطر كثيرًا ما تُقتطع في المحررات ويتجاهلها القارئ.
التعليق متعدد الأسطر في جافا سكريبت
تلجأ إلى /* */ في حالتين: حين يحتاج التعليق إلى أكثر من سطر، وحين يقع التعليق في منتصف تعبير برمجي.
لكن انتبه لفخ مهم: التعليقات من نوع block comment لا تتداخل. أول */ يصادفه المُفسِّر يُنهي التعليق، حتى لو كنت تظن أنك ما زلت داخل تعليق خارجي:
/* خارجي /* داخلي */ لا يزال خارجيًا */
// SyntaxError — علامة */ الأولى أغلقت الكتلة،
// و "still outer */" أصبحت الآن كودًا غير صالح.
إذا احتجت إلى تعليق كود يحتوي أصلًا على /* */، فاستخدم // في بداية كل سطر بدلًا من ذلك.
تعطيل الكود بالتعليقات
أثناء تصحيح الأخطاء، ستحتاج كثيرًا إلى تعطيل بضعة أسطر مؤقتًا. وكلا نوعَي التعليقات يؤدي الغرض:
في كل محرر أكواد فيه اختصار لهذا الغرض — Ctrl+/ على ويندوز/لينكس، وCmd+/ على الماك — يقوم بإضافة أو إزالة // من الأسطر المحددة. تعلّمه مرة واحدة، وراح تستخدمه يومياً.
الكود المعطّل بالتعليقات يُفترض أن يكون مؤقتاً فقط. لا تترك مقابر من الأكواد الميتة في مشروعك مع تعليق فوقها مثل // النسخة القديمة، نحتفظ بها للاحتياط. نظام التحكم بالإصدارات (Git) يحفظ لك النسخ القديمة. احذفها وخلاص.
اكتب التعليق لشرح "لماذا"، لا "ماذا"
هذه هي القاعدة الذهبية التي تفرّق بين التعليق المفيد والتعليق الذي يُعتبر ضوضاء لا أكثر. الكود نفسه يوضّح ماذا يفعل، أما التعليق الجيد فيشرح لماذا يفعله.
تعليق زائد لا فائدة منه:
هذه التعليقات لا تضيف للقارئ أي شيء لم يقله الكود أصلًا. قارن بين الحالتين:
كلا التعليقَين يُفصحان عن شيء لا يستطيع القارئ استنتاجه من الكود وحده — قيد خارجي، أو سلوك غريب موثَّق. هذا هو المعيار. إذا كان حذف التعليق لن يُربك أحدًا، فالتعليق إذن لم يكن يؤدي دورًا حقيقيًا.
JSDoc: تعليقات تقرأها الأدوات
JSDoc هو اصطلاح لكتابة تعليقات متعددة الأسطر في جافا سكريبت تصف الدوال بصيغة منظَّمة. المحررات وأدوات فحص الأنواع تقرأ هذه التعليقات وتمنحك إكمالًا تلقائيًا أفضل وتوثيقًا يظهر عند التمرير فوق الدالة:
الـ /** (بنجمتين) في البداية هو اللي يميّز التعليق كـ JSDoc بدل ما يكون تعليقًا متعدد الأسطر عاديًا. مش لازم تستخدم JSDoc مع كل دالة — فائدته تظهر أكثر مع الـ APIs العامة، والدوال المساعدة المشتركة، وأي مكان ما تكون فيه الأنواع واضحة من الكود نفسه.
عادات مفيدة يستحسن الالتزام بها
- خلّي التعليق قريبًا من الكود اللي يشرحه. التعليق اللي يبعد عشرة أسطر عن السطر المقصود عادةً ما يصير غير متزامن مع الكود مع أول تعديل.
- حدّث التعليقات لمّا تغيّر الكود. التعليق القديم اللي ما تم تحديثه أسوأ من عدم وجود تعليق أصلًا — لأنه يضلّل القارئ التالي بشكل مباشر.
- الأسماء الواضحة أفضل من كثرة التعليقات.
const d = 86400000;يحتاج تعليق يشرحه. أماconst MILLISECONDS_PER_DAY = 86_400_000;فما يحتاج شيئًا. - علّم المشاكل المؤقتة بـ
TODO:أوFIXME:. معظم المحررات تُبرز هذه الكلمات بلون مميز، وسهل تبحث عنها لاحقًا باستخدام grep.
ملاحظة مهمة: الفرق بين تعليقات HTML وتعليقات جافا سكريبت
لو كنت تكتب كود جافا سكريبت داخل ملف HTML، انتبه ولا تخلط بين أسلوبَي التعليقات. لغة HTML تستخدم <!-- -->، أما جافا سكريبت فتستخدم // و /* */. وداخل وسم <script>، لن يعمل إلا أسلوب تعليقات جافا سكريبت فقط:
<script>
// صحيح — تعليق JS داخل <script>
/* صحيح أيضاً */
<!-- خطأ — هذا تعليق HTML وسيُعطِّل شيفرة JS لديك -->
console.log("مرحباً");
</script>
تاريخيًا، كانت المتصفحات تتسامح مع وجود <!-- --> داخل وسوم السكريبت لأسباب تتعلق بدعم المتصفحات القديمة جدًا، لكن اعتبر هذا الأسلوب مهجورًا ولا تلتفت إليه.
الخطوة التالية: الإعلان عن المتغيرات
بعد أن أصبح بإمكانك إضافة التعليقات لشرح الكود، حان وقت كتابة الكود نفسه. تتيح لك جافا سكريبت ثلاث طرق للإعلان عن المتغيرات: let و const و var، واختيار الطريقة المناسبة هو أول قرار حقيقي ستتخذه في كل سطر تكتبه. هذا ما سنتناوله تاليًا.
الأسئلة الشائعة
كيف أكتب تعليقاً في جافا سكريبت؟
استخدم // للتعليق على سطر واحد — كل ما يأتي بعدها في نفس السطر يتم تجاهله. أما /* ... */ فهو تعليق متعدد الأسطر يمكن أن يمتد لأكثر من سطر. الاثنان يعملان في أي مكان داخل ملف .js وكذلك داخل وسم <script> في HTML.
ما الفرق بين // و /* */ في جافا سكريبت؟
// ينتهي تلقائياً عند نهاية السطر الحالي. أما /* */ فيبدأ عند /* وينتهي عند أول */ يقابله، فيصلح للتعليقات الطويلة أو حتى لوضع ملاحظة في منتصف تعبير برمجي. القاعدة العملية: استخدم // للملاحظات القصيرة، و/* */ حين تحتاج أكثر من سطر أو تريد التعليق على جزء معين داخل تعبير.
كيف أعطّل (أعلّق على) مجموعة أكواد دفعة واحدة؟
غلّفها داخل /* */، أو ضع // في بداية كل سطر. معظم المحررات فيها اختصار جاهز — Ctrl+/ (أو Cmd+/ على ماك) يفعّل ويلغي // على الأسطر المحددة. تجنّب تداخل /* */ داخل تعليق /* */ آخر، لأن أول */ سيغلق التعليق الخارجي وستحصل على خطأ في الصياغة.
متى يجب أن أكتب تعليقاً فعلاً؟
اكتب التعليق ليشرح لماذا، وليس ماذا. إذا كان الكود يفعل شيئاً غير واضح — حلاً مؤقتاً، قاعدة عمل، أو حيلة لتحسين الأداء — فاشرح السبب. لا تعيد سرد ما يقوله الكود أصلاً. وتذكّر أن اختيار اسم جيد للمتغير أو الدالة يغنيك عن أغلب التعليقات.
