عند العمل مع الأكواد في بداية الأمر تكون بسيطة مفهومة وسرعان ماتجد نفسك تكتب السطر تلو السطر لتصل لمئات الأسطر والملفات المتشعبة وتصبح صعبة الفهم مع مرور الوقت تتضح لك بشكل أكبر عند العمل على مشاريع برمجية تحتاج تنظيم وتطوير مستمر حيث أن أهم جوانب المشاريع البرمجية والتي يتجاهلها الكثير من المطورين توثيق الأكواد البرمجية لتسهل عليك فهم عمل أي كود برمجي عند الرجوع إليه بعد زمن لتطويره أو حل مشكلة فيه والفائدة لاتقف عند هذه النقطة بل مهمة لو كان العمل جماعي ويوجد أكثر من شخص بفريق التطوير فإنه يسهل عملية فهم الأكواد ويسهل عملية التطوير بإختصار الوقت المستغرق من قبل أي مطور لفهم الكود ثم البدء بالتطوير ومن هنا تأتي أهمية PHP DocBlocks
نبذة عامة عن PHP DocBlocks
هل سبق وحاولت قراءة أكواد غيرك أو عملت على مشاريع مع عدة أشخاص إن كانت الإجابة نعم فأنت تعلم صعوبة فهم الأكواد وحتى بعض التعليقات غير كافية لشرح عمل الكود البرمجي حيث لكل مطور اسلوب خاص فيه والبعض لايستطيع أن يوصل المعنى لبقية المطورين ومن هنا أتت الحاجة لوجود قوانين لكتابة التعليقات بين مبرمجي PHP لتوحيدها لكي تسهل عملية الفهم عند عرض الأكواد البرمجية حيث تم تطوير اسلوب تعليقات خاص في PHP وتم دعم هذا الاسلوب من قبل الكثير من محررات الأكواد مثل PhpStorm و NetBeans و Zend Studio و Eclipse وبقية المحررات وتم تطوير أداة قوية لتوليد مستندات من هذه التعليقات بكل سهولة لملفات HTML او PDF او CHM هذه الاداة هي PhpDoc وهي إختصار لكلمة PhpDocumentor وهي نفس الجهة المسؤولة عن تطوير وتحديث هذا الأسلوب ليستخدمه بقية المطورين عند كتابة التعليقات
متى أستخدم PHP DocBlocks
يمكنك كتابة التعليقات بإستخدام DocBlocks عند التعامل مع أحد هذه العناصر في البرمجة:
جميع تعليقات DocBlocks يجب ان تحاط بـ DocComment وهي
تبدأ بـ
/** تنتهي بـ
*/ وجميع الأسطر بين علامة البداية وعلامة النهاية يجب أن تبدأ بنجمة ثم تقوم بكتابة التعليق
* مثال:
<?php /** * This is a DocBlock. */ function Foo() { } عند كتابة أسطر DocBlocks ممكن تقسيمها لثلاث أقسام رئيسية كالتالي:
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 خذ بعين الإعتبار التالي:
مثال:
<?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
عند كتابة التعليقات فأنت أحيانا ترغب بعمل تنسيق لهذه التعليقات سواء كان في 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
هل سبق وحاولت قراءة أكواد غيرك أو عملت على مشاريع مع عدة أشخاص إن كانت الإجابة نعم فأنت تعلم صعوبة فهم الأكواد وحتى بعض التعليقات غير كافية لشرح عمل الكود البرمجي حيث لكل مطور اسلوب خاص فيه والبعض لايستطيع أن يوصل المعنى لبقية المطورين ومن هنا أتت الحاجة لوجود قوانين لكتابة التعليقات بين مبرمجي 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
جميع تعليقات 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 تسطيع إضافة إسم الشخص و بريده الإلكتروني في التعليق بصيغة محددة
مثال:
<?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
- @api
- @author
- @category
- @copyright
- @deprecated
- @example
- @filesource
- @global
- @ignore
- @internal
- @license
- @link
- @method
- @package
- @param
- @property
- @property-read
- @property-write
- @return
- @see
- @since
- @source
- @subpackage
- @throws
- @todo
- @uses
- @var
- @version
عند كتابة التعليقات فأنت أحيانا ترغب بعمل تنسيق لهذه التعليقات سواء كان في 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> */ في الختام
هذه التعليقات من أهم خطوات بناء أي مشروع برمجي ناجح والكثير من المبرمجين يستهين أو لايعطيها أهمية بحجة إذا فتحت المشروع ساعة بالكثير وأنا فاهم الأكواد أو عذر ماعندي وقت أكتبها وكلها حجج خاطئة وراح تضيع وقتك و وقت من يشتغل معك أو من راح يستلم الشغل بعدك الكثير من المحررات الحديثة تسهل عملية توليد هذه التلعيقات وكل ماعليك كتابة وصف بسيط لعمل أي كود تقوم بكتابته تأكد عندما يكبر مشروعك وترجع لنفس الكود بدل الساعة او الساعتين لتفهم عمل الكود راح تفهمه مباشرة لوجود التعليق المناسب وبالصيغة المناسبة والواضحة بشكل أسرع وأسهل لك وراح يوفر جهدك سواء بالتطوير أو حل مشكلة بالمشروع.
