Php COMMENTS

 في لغة PHP، تُستخدم التعليقات (Comments) لإضافة ملاحظات أو شروحات داخل كود البرنامج دون أن يتم تنفيذها من قبل مُفسّر PHP. تُعتبر التعليقات أداة مهمة جدًا للمبرمجين للأسباب التالية:

• شرح الكود: تُساعد التعليقات في توضيح وظيفة أجزاء الكود المختلفة، مما يجعل فهم الكود أسهل على المبرمجين الآخرين (أو حتى على نفسك لاحقًا).
• توثيق الكود: تُستخدم التعليقات لتوثيق الكود، أي شرح كيفية عمله، والمتغيرات المستخدمة، والوظائف، وغيرها من التفاصيل المهمة.
• تصحيح الأخطاء (Debugging): يُمكن استخدام التعليقات لإيقاف تنفيذ أجزاء معينة من الكود مؤقتًا أثناء عملية تصحيح الأخطاء.

أنواع التعليقات في PHP:

يوجد ثلاثة أنواع رئيسية من التعليقات في PHP:

1. التعليقات السطرية (Single-line comments): تبدأ بـ // وتستمر حتى نهاية السطر. أي شيء بعد // على نفس السطر سيتم تجاهله.

   PHP

   <?php
   // هذا تعليق سطري بسيط
   echo "مرحباً بالعالم!"; // هذا تعليق سطري آخر بعد الكود
   ?>

2. التعليقات متعددة الأسطر (Multi-line comments): تبدأ بـ /* وتنتهي بـ */. يُمكن أن تمتد هذه التعليقات على عدة أسطر.

   PHP

   <?php
   /*
    * هذا تعليق متعدد الأسطر.
    * يُمكن أن يمتد على عدة أسطر كما تلاحظ.
    * يُستخدم لشرح أجزاء كبيرة من الكود.
    */
   echo "هذا مثال على تعليق متعدد الأسطر.";
   ?>

3. تعليقات الوثائق (Documentation comments) أو PHPDoc: تبدأ بـ /** وتنتهي بـ */. تُستخدم هذه التعليقات لإنشاء وثائق تلقائية للكود باستخدام أدوات مثل PHPDoc. تُستخدم هذه التعليقات عادةً قبل تعريف الدوال والأصناف والمتغيرات لشرح وظيفتها ومعاملاتها وقيم الإرجاع.

   PHP

   <?php
   /**
    * دالة تقوم بجمع رقمين.
    *
    * @param int $a الرقم الأول.
    * @param int $b الرقم الثاني.
    * @return int مجموع الرقمين.
    */
   function جمع_رقمين(int $a, int $b): int {
       return $a + $b;
   }
   ?>

متى تستخدم كل نوع من التعليقات؟

• استخدم التعليقات السطرية لشرح أسطر الكود الفردية أو لإضافة ملاحظات سريعة.
• استخدم التعليقات متعددة الأسطر لشرح أجزاء أكبر من الكود أو لإيقاف تنفيذ أجزاء من الكود مؤقتًا.
• استخدم تعليقات الوثائق لتوثيق الكود بشكل احترافي وإنشاء وثائق تلقائية.

باختصار، التعليقات هي جزء أساسي من كتابة كود PHP نظيف وقابل للصيانة. استخدمها بشكل جيد لشرح كودك وجعله مفهومًا للآخرين (ولنفسك في المستقبل).