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

Ali Majrashiمنذ 8 سنوات

عند العمل مع الأكواد في بداية الأمر تكون بسيطة مفهومة وسرعان ماتجد نفسك تكتب السطر تلو السطر لتصل لمئات الأسطر والملفات المتشعبة وتصبح صعبة الفهم مع مرور الوقت تتضح لك بشكل أكبر عند العمل على مشاريع برمجية تحتاج تنظيم وتطوير مستمر حيث أن أهم جوانب المشاريع البرمجية والتي يتجاهلها الكثير من المطورين توثيق الأكواد البرمجية لتسهل عليك فهم عمل أي كود برمجي عند الرجوع إليه بعد زمن لتطويره أو حل مشكلة فيه والفائدة لاتقف عند هذه النقطة بل مهمة لو كان العمل جماعي ويوجد أكثر من شخص بفريق التطوير فإنه يسهل عملية فهم الأكواد ويسهل عملية التطوير بإختصار الوقت المستغرق من قبل أي مطور لفهم الكود ثم البدء بالتطوير ومن هنا تأتي أهمية 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 ممكن تقسيمها لثلاث أقسام رئيسية كالتالي:

Summary (ملخص)
Description (وصف)
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>
 */

في الختام

هذه التعليقات من أهم خطوات بناء أي مشروع برمجي ناجح والكثير من المبرمجين يستهين أو لايعطيها أهمية بحجة إذا فتحت المشروع ساعة بالكثير وأنا فاهم الأكواد أو عذر ماعندي وقت أكتبها وكلها حجج خاطئة وراح تضيع وقتك و وقت من يشتغل معك أو من راح يستلم الشغل بعدك الكثير من المحررات الحديثة تسهل عملية توليد هذه التلعيقات وكل ماعليك كتابة وصف بسيط لعمل أي كود تقوم بكتابته تأكد عندما يكبر مشروعك وترجع لنفس الكود بدل الساعة او الساعتين لتفهم عمل الكود راح تفهمه مباشرة لوجود التعليق المناسب وبالصيغة المناسبة والواضحة بشكل أسرع وأسهل لك وراح يوفر جهدك سواء بالتطوير أو حل مشكلة بالمشروع.

كلمات دليلية:

إعجاب

أعجبني

10119

مشاهدات

تلقائي