شرح التعليقات في PHP — متى نكتب Comment ومتى نتجنبها؟
كل مبرمج يعود إلى كوده القديم بعد أيام أو أسابيع ويتساءل: "لماذا كتبت هذا بهذا الشكل؟" هنا تظهر قيمة التعليقات (Comments) في PHP.
التعليق لا يُنفذ، ولا يظهر للمستخدم، لكنه يساعدك أنت أو فريقك على فهم الكود بسرعة.
ما هي التعليقات في PHP؟
التعليقات هي نصوص للشرح داخل الملف البرمجي. مفسر PHP يتجاهلها بالكامل أثناء التنفيذ.
أنواع التعليقات في PHP
1) تعليق سطر واحد
يستخدم عندما تريد ملاحظة سريعة فوق سطر أو بجانبه.
// هذا تعليق سطر واحد
# وهذا أيضاً تعليق سطر واحد2) تعليق متعدد الأسطر
يستخدم عندما تحتاج شرحاً أطول يمتد على عدة أسطر.
/*
هذا تعليق
يغطي عدة أسطر
*/مثال عملي كامل
<?php
// اسم المستخدم القادم من قاعدة البيانات
$name = "Rachid";
/*
نضيف هذه الرسالة للترحيب بالمستخدم
أول مرة بعد تسجيل الدخول
*/
echo "مرحباً " . $name;
?>في هذا المثال، التعليقات جعلت هدف كل جزء واضحاً بدون التأثير على تشغيل البرنامج.
استخدام التعليق لتعطيل كود مؤقتاً
أثناء التجربة أو التصحيح، قد تحتاج تعطيل سطر أو جزء من الكود مؤقتاً:
<?php
echo "السطر الأول يعمل";
// echo "هذا السطر معطل مؤقتاً";
echo "السطر الثالث يعمل";
?>هذه طريقة مفيدة أثناء التعلم، لكن في المشاريع الحقيقية حاول تنظيف الكود لاحقاً.
قبل/بعد: تعليق ضعيف مقابل تعليق مفيد
تعليق ضعيف (يكرر الواضح):
// طباعة الاسم
echo $name;تعليق مفيد (يشرح السبب):
// نستخدم الاسم المختصر هنا لأنه يظهر في شريط التنقل الضيق
echo $shortName;أخطاء شائعة في كتابة التعليقات
- الإكثار من التعليقات: يجعل الملف مزدحماً وصعب القراءة.
- تعليقات قديمة غير محدثة: أخطر من عدم وجود تعليق لأنها تضلل القارئ.
- وصف تفاصيل بسيطة جداً: إذا الكود واضح، لا تشرح الواضح.
- نسيان إغلاق تعليق متعدد الأسطر: يسبب أخطاء syntax.
أفضل ممارسات سريعة
- اكتب تعليقاً عندما يكون القرار التقني غير بديهي.
- اجعل التعليق قصيراً ومباشراً.
- حدّث التعليق عند تعديل الكود المرتبط به.
- استخدم أسماء متغيرات واضحة لتقليل الحاجة للتعليقات.
تمرين سريع
أنشئ ملفاً صغيراً فيه 4 أسطر كود PHP، ثم:
- أضف تعليق سطر واحد يشرح مهمة السطر الأول.
- أضف تعليق متعدد الأسطر يشرح هدف جزء من الكود.
- عطّل سطراً واحداً بالتعليق ثم شغّل الملف ولاحظ الفرق.
الأسئلة الشائعة — FAQ
هل التعليقات تُنفذ مع كود PHP؟
لا. مفسر PHP يتجاهل التعليقات بالكامل، لذلك هي للشرح والتنظيم فقط.
ما الفرق بين // و /* */؟
// (وأيضاً #) لتعليق سطر واحد، بينما /* */ للتعليقات متعددة الأسطر.
هل يمكن استخدام التعليق لتعطيل كود مؤقتاً؟
نعم، وهذا شائع أثناء التجربة. لكن لا تترك كوداً معطلاً لفترة طويلة داخل المشروع النهائي.
ما أفضل نوع تعليق في المشاريع الحقيقية؟
التعليق القصير الذي يشرح السبب أو القرار، مع كود واضح التسميات. هذا أفضل من كتابة تعليقات كثيرة بلا قيمة.
جاهز للخطوة القادمة؟ انتقل إلى: المتغيرات في PHP.