How to Make PHP Comments (And Why You Should Know)
التعليقات بلغة PHP
التعليق في كود PHP هو سطر لا يتم تنفيذه كجزء من برنامج. الغرض الوحيد منه هو أن يقرأه شخص ينظر إلى الكود.
يمكن استخدام التعليقات من أجل:
- السماح للآخرين بفهم التعليمات البرمجية الخاصة بك
- ذكر نفسك بما فعلته – لقد اختبر معظم المبرمجين العودة إلى عملهم بعد عام أو عامين والاضطرار إلى إعادة معرفة ما فعلوه. يمكن أن تذكرك التعليقات بما كنت تفكر فيه عندما كتبت الكود
1. Single-line Comments
“MUST use two forward slashes“
e.g. // My comment
2. Multi-line Comments
MUST use the block format
i.e. /** ↵ * My comment ↵ */
3. Header Comments
SHOULD use the block format
i.e. /** ↵ * Name of code section ↵ */
4. Divider Comments
SHOULD use the block format with asterisks in between
i.e. /** 75 asterisks */
5. Comments
MUST be on their own line
i.e. ↵ // My comment
6. Blocks of Code
SHOULD be explained or summarized
e.g. // Compare user accounts from export against expired accounts in system
7. Ambiguous Numbers
MUST be clarified
e.g. // 1,000 processable records per hour API limit
8. External Variables
MUST be clarified
e.g. // Database object included in file.php
1. Single-line Comments
يجب أن تستخدم التعليقات ذات السطر الواحد شرطتين مائلتين للأمام.
✖ Incorrect
↳ غير صحيح لأنه يستخدم وللتعليق من سطر واحد./**/
✔ Correct
2. Multi-line Comments
يجب أن تستخدم التعليقات متعددة الأسطر تنسيق الكتلة.
✖ Incorrect
↳ غير صحيح لأنه يستخدم لتعليق متعدد الأسطر.//
✔ Correct
3. Header Comments
يجب أن تستخدم Header comments تنسيق الكتلة ” block format”.
4. Divider Comments
يجب أن تستخدم Divider comments تنسيق الكتلة ” block format” مع 75 علامة نجمية “asterisks “بينهما.
✖ Incorrect
↳ غير صحيح لأنه يستخدم بدلا من .#*
↳ غير صحيح لأنه يستخدم # instead of *.
↳ غير صحيح لأنه يستخدم 10 بدلا من 75 .*
✔ Correct
5. Comments
يجب أن يكون التعليق على خطهم الخاص
✖ Incorrect
↳ غير صحيح لأنه ليس على خطه الخاص.// Prints welcome message
✔ Correct
6. Blocks of Code
يجب شرح أو تلخيص كتل التعليمات البرمجية.
Acceptable
↳ مقبول ، ولكن يجب شرح كتلة التعليمات البرمجية أو تلخيصها.
✔ Preferred
7. Ambiguous Numbers
يجب توضيح الأرقام الغامضة.
✖ Incorrect
↳ غير صحيح لأنه لم يتم توضيحه.1000
✔ Correct
8. External Variables
يجب توضيح المتغيرات الخارجية.
✖ Incorrect
↳ غير صحيح لأن مصدر غير واضح.$users
✔ Correct
