عرض مشاركة واحدة
  #1  
قديم 05-28-2021, 03:14 AM
الصورة الرمزية الادارة كريم
الادارة كريم 
مشرف سابق
 
تاريخ التسجيل: May 2021
الدولة: مصر
المشاركات: 397
معدل تقييم المستوى: 18
الادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to behold


افتراضي كتابة التعليقات البرمجية في PHP بواسطة DocBlocks

 

عند العمل مع الأكواد في بداية الأمر تكون بسيطة مفهومة وسرعان ماتجد نفسك تكتب السطر تلو السطر لتصل لمئات الأسطر والملفات المتشعبة وتصبح صعبة الفهم مع مرور الوقت تتضح لك بشكل أكبر عند العمل على مشاريع برمجية تحتاج تنظيم وتطوير مستمر حيث أن أهم جوانب المشاريع البرمجية والتي يتجاهلها الكثير من المطورين توثيق الأكواد البرمجية لتسهل عليك فهم عمل أي كود برمجي عند الرجوع إليه بعد زمن لتطويره أو حل مشكلة فيه والفائدة لاتقف عند هذه النقطة بل مهمة لو كان العمل جماعي ويوجد أكثر من شخص بفريق التطوير فإنه يسهل عملية فهم الأكواد ويسهل عملية التطوير بإختصار الوقت المستغرق من قبل أي مطور لفهم الكود ثم البدء بالتطوير ومن هنا تأتي أهمية PHP DocBlocks
نبذة عامة عن PHP DocBlocks
هل سبق وحاولت قراءة أكواد غيرك أو عملت على مشاريع مع عدة أشخاص إن كانت الإجابة نعم فأنت تعلم صعوبة فهم الأكواد وحتى بعض التعليقات غير كافية لشرح عمل الكود البرمجي حيث لكل مطور اسلوب خاص فيه والبعض لايستطيع أن يوصل المعنى لبقية المطورين ومن هنا أتت الحاجة لوجود قوانين لكتابة التعليقات بين مبرمجي PHP لتوحيدها لكي تسهل عملية الفهم عند عرض الأكواد البرمجية حيث تم تطوير اسلوب تعليقات خاص في PHP وتم دعم هذا الاسلوب من قبل الكثير من محررات الأكواد مثل PhpStorm و NetBeans و Zend Studio و Eclipse وبقية المحررات وتم تطوير أداة قوية لتوليد مستندات من هذه التعليقات بكل سهولة لملفات HTML او PDF او CHM هذه الاداة هي PhpDoc وهي إختصار لكلمة PhpDocumentor وهي نفس الجهة المسؤولة عن تطوير وتحديث هذا الأسلوب ليستخدمه بقية المطورين عند كتابة التعليقات
متى أستخدم PHP DocBlocks
يمكنك كتابة التعليقات بإستخدام DocBlocks عند التعامل مع أحد هذه العناصر في البرمجة:

  • Function
  • Constant
  • Class
  • Interface
  • Trait
  • Class constant
  • Property
  • Method
  • Files
  • ()include() / require
طريقة كتابة PHP DocBlocks
جميع تعليقات DocBlocks يجب ان تحاط بـ DocComment وهي
تبدأ بـ
/** تنتهي بـ
*/ وجميع الأسطر بين علامة البداية وعلامة النهاية يجب أن تبدأ بنجمة ثم تقوم بكتابة التعليق
* مثال:
<?php /** * This is a DocBlock. */ function Foo() { } عند كتابة أسطر DocBlocks ممكن تقسيمها لثلاث أقسام رئيسية كالتالي:
  1. Summary (ملخص)
  2. Description (وصف)
  3. Tags (الكلمات المفتاحية أو الوسوم)
ملاحظة: عند كتابة التعليقات تستطيع إستخدام جميع هذه الأقسام دفعة واحدة أو تستطيع إختيار مايناسبك عند كتابة أي تعليق فجميعها إختيارية
Summary (الملخص)
وهو تعليق بسيط غالبا يكون في سطر واحد وأحيانا يطلق عليه إسم Short Descripton ينتهي بنقطة أو سطر جديد يفصله عن التعليق الذي بعده
مثال:
<?php /** * A summary informing the user what the associated element does. */ Description (الوصف)
وهو تعليق مفصل ويحتوي العديد من الأسطر ويطلق عليه أيضا Long Description يمكن أن يحتوي على وصف مفصل لطريقة عمل الكود أو حتى أمثلة لشرح طريقة عمل الأكواد و ينتهي تعليق Description عندما يتبعه أول Tag أو عند إنتهاء DocBlocks
مثال:
<?php /** * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element * and to provide some background information or textual references. */ Tags (الكلمات المفتاحية أو الوسوم)
هي كلمات مميزة تبدأ بعلامة @ قبلها تعطيك المزيد من المعلومات بمجرد تعريفها وهنا قوة DocBlocks حيث تم توحيد ودعم كلمات مفتاحية tags مميزة ولكل واحد منها معنى خاص يختصر الكثير من جهدك في محاولة التعبير عن محتوى الكود مثلا عند إنشاء دالة تستطيع إستخدام الكلمة @param لتعريف نوع المتغيرات التي تقبلها الدالة او إستخدام الكلمة @return لتعريف نوع القيم المرجعة بعد معالجة وتنفيذ الأوامر
مثال:
<?php /** * @param string $param With a *description* of this argument, these may also * span multiple lines. * * @return void */ function Foo($param) { } عند إستخدام Tags خذ بعين الإعتبار التالي:
  • عند إستخدام Tags يمكنك كتابة تعليق يصف Tag ويمكن أن يتمد لعدة أسطر
  • كل Tag يبدأ بسطر جديد عند إستخدامه
  • يوجد عدد من Tgas الممكن كتابتها ضمن أسطر Description أو Summary وتسمى بـ inline-tags
  • بعض Tags لديها خيارات إضافية عند إستخدامها مثلا عند إستخدام @author تسطيع إضافة إسم الشخص و بريده الإلكتروني في التعليق بصيغة محددة
كما ذكرنا سابقا فإنه من الممكن إستخدام هذه الأقسام لكتابة تعليق على أي من العناصر المذكورة سابقا ومن الممكن أيضا إستخدام أكثر من Tag (وسم) بنفس التعليق
مثال:
<?php /** * A summary informing the user what the associated element does. * * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element * and to provide some background information or textual references. * * @param string $param With a *description* of this argument, these may also * span multiple lines. * * @return void */ function Foo($param) { } بهذا المثال إستخدمنا Summary و Description و Tags مجتمعة لكتابة تعليق لدالة Function وهي أحد العناصر الممكن كتابة تعليق لها
قائمة Tags (الوسوم) المتاحة:
لكل Tag معنى خاص وطريقة كتابة لمعرفة معنى كل Tag وطريقة إستخدامه كل ماعليك هو الضغط على إسم Tag
تنسيق PHP DocBlocks
عند كتابة التعليقات فأنت أحيانا ترغب بعمل تنسيق لهذه التعليقات سواء كان في Summury أو Description أو عند إستخدام Tags المميز هنا أنك تسطيع إستخدام أكواد HTML أو أكواد Markdwon لتنسيق التعليقات
مثال:
<?php /** * Example of using lists * * Markdown list * - Item #1 * - Item #2 * - Item #3 * * HTML list: * <ul> * <li>Item 1</li> * <ul> * <li>Item 1.1</li> * <li>Item 1.2</li> * </ul> * <li>Item 2</li> * </ul> */ في الختام
هذه التعليقات من أهم خطوات بناء أي مشروع برمجي ناجح والكثير من المبرمجين يستهين أو لايعطيها أهمية بحجة إذا فتحت المشروع ساعة بالكثير وأنا فاهم الأكواد أو عذر ماعندي وقت أكتبها وكلها حجج خاطئة وراح تضيع وقتك و وقت من يشتغل معك أو من راح يستلم الشغل بعدك الكثير من المحررات الحديثة تسهل عملية توليد هذه التلعيقات وكل ماعليك كتابة وصف بسيط لعمل أي كود تقوم بكتابته تأكد عندما يكبر مشروعك وترجع لنفس الكود بدل الساعة او الساعتين لتفهم عمل الكود راح تفهمه مباشرة لوجود التعليق المناسب وبالصيغة المناسبة والواضحة بشكل أسرع وأسهل لك وراح يوفر جهدك سواء بالتطوير أو حل مشكلة بالمشروع.


الموضوع الأصلي : كتابة التعليقات البرمجية في PHP بواسطة DocBlocks || الكاتب : الادارة كريم || المصدر : منتدى مجمع التطوير

 

رد مع اقتباس