الرئيسية المنتدى مركز رفع الصور صفحتنا على الفيس قناة اليوتيوب صفحتنا على تويتر واتس اب قوانين المنتدى
منتدى مجمع التطوير    

العودة   منتدى مجمع التطوير > المنتدى المتخصص > لغـات البرمجـة والمشـاريع الجـاهزة > برمجة الويب web development

الملاحظات

برمجة الويب web development يهتم ببرامج الويب php, Sql, Java ,asp.net ,xml ,html

آخر 10 مشاركات افعل الخير ولا تنظر جزاءه الا من الله (الكاتـب : admin - مشاركات : 0 - المشاهدات : 37 - الوقت: 08:12 PM - التاريخ: 07-27-2021)           »          دليلك لبناء الباك لينك Backlink لموقعك بطريقة صحيحة (الكاتـب : admin - مشاركات : 2 - المشاهدات : 281 - الوقت: 10:15 PM - التاريخ: 07-26-2021)           »          ملف ال robots.txt وتوجيه عناكب محركات البحث لموقعك (الكاتـب : admin - مشاركات : 2 - المشاهدات : 346 - الوقت: 01:24 PM - التاريخ: 07-21-2021)           »          أهلا وسهلا أليت تيم رياك (الكاتـب : رياك مشار - مشاركات : 2 - المشاهدات : 275 - الوقت: 05:58 PM - التاريخ: 07-03-2021)           »          تحميل لعبة فرايدي نايت فانكن Friday Night Funkin للكمبيوتر 2021 (الكاتـب : الادارة كريم - آخر مشاركة : admin - مشاركات : 2 - المشاهدات : 524 - الوقت: 10:41 PM - التاريخ: 07-01-2021)           »          برنامج البيع بالتقسيط مجاني مصمم بالاكسيس (الكاتـب : ابن الوليد - آخر مشاركة : admin - مشاركات : 1 - المشاهدات : 644 - الوقت: 04:37 AM - التاريخ: 06-25-2021)           »          الصحابي الجليل سعد بن معاذ الأنصاري (الكاتـب : admin - مشاركات : 0 - المشاهدات : 294 - الوقت: 01:25 AM - التاريخ: 06-25-2021)           »          كيفية صلاة الحاجة (الكاتـب : admin - مشاركات : 0 - المشاهدات : 266 - الوقت: 12:13 AM - التاريخ: 06-25-2021)           »          Format FactoryV5.7.5.0 (الكاتـب : admin - مشاركات : 0 - المشاهدات : 304 - الوقت: 11:01 PM - التاريخ: 06-24-2021)           »          رجل أقسم بأن لا يتزوج حتى يشاور مائة رجل (الكاتـب : admin - مشاركات : 0 - المشاهدات : 308 - الوقت: 09:57 PM - التاريخ: 06-24-2021)

إضافة رد
 
أدوات الموضوع انواع عرض الموضوع
  #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 || الكاتب : الادارة كريم || المصدر : منتدى مجمع التطوير

 

رد مع اقتباس
إضافة رد

مواقع النشر (المفضلة)

أدوات الموضوع
انواع عرض الموضوع

تعليمات المشاركة
لا تستطيع إضافة مواضيع جديدة
لا تستطيع الرد على المواضيع
لا تستطيع إرفاق ملفات
لا تستطيع تعديل مشاركاتك

BB code is متاحة
كود [IMG] متاحة
كود HTML معطلة

الانتقال السريع

المواضيع المتشابهه
الموضوع كاتب الموضوع المنتدى مشاركات آخر مشاركة
[شرح] استخدم Visual Studio لإنشاء مكتبة ديناميكية مكتبة ثابتة ، وتحميل الادارة كريم برامج Microsoft Visual 1 06-03-2021 01:44 PM
[شرح] كتب لتعليم لغة css admin برامج Microsoft Visual 1 05-31-2021 01:42 AM
[شرح] التعليقات و حساسية الكتابه بي اتش بي الادارة كريم برمجة الويب web development 0 05-28-2021 02:52 AM
[C++] كتاب تعلم البرمجة بلغة السى c للمبتدئين admin برامج Microsoft Visual 0 05-13-2021 06:28 PM

 

موقع ومنتديات مجمع التطوير موقع يختص بالبرمجة والبرامج المساعدة  للتصاميم والأدوات المساعدة ,مع تقديم العون والمساعدة لكل مبرمج من خلال الأقسام المحددة , كما نعرض الأعمال الجاهزة والمفتوحة المصدر. ويهتم أيضا بالتصاميم والجرافيك وبرامجها وعرض التصاميم وملحقات التصاميم والأدوات المساعدة .كما نتمنى التوفيق لنا ولكم مع أجمل تحية مقدمة منا. 

  • الرئــيســية

  • الــمنــتـدى

  • مركز الرفع

  • التسـجـيل

  • قوانين المنتدى

  • التعـلـيمـات

  • الترقيات

check pagerank

 Flag Counter

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


Powered by vBulletin® Copyright ©2000 - 2021, Jelsoft Enterprises Ltd.
جميع الحقوق محفوظة لمجمع التطوير