منتدى رياض الجنة - Riad Al-Ganah - الدرس الواحد والسبعون : XML Commenting

بسم الله الرحمن الرحيم .
السلام عليكم ورحمة الله وبركاته .

بما أن دروسنا في مجال التطبيقات العامة تقريباً انتهى ، وقبل البدء في عالم ASP.net سنراجع على عدة دروس سريعة ، درسنا اليوم حول ما يعرف باسم XML Commenting .

بالواقع فإن عمل Comments للأكواد يعد أمراً في غاية الأهمية خصوصاً في حالة المشاريع الكبيرة ، حيث تستطيع مراقبة كودك كما يستطيع اي شخص آخر بقليل من الجهد معرفة كودك والاكمال عليه حتى ولو بعد توقفك عن العمل في نفس الكود بفترة طويلة جداً .

وكما عرفنا في بدايات هذه الدروس ، يتم عمل ال Comment بالشكل التالي :

C#:

كود PHP:


		
			
// here we will do something, set x=startvalue

x = FirstClass.Default();

vb.net:

كود PHP:


		
			
' here we will do something, set x=startvalue

x = FirstClass.Default()

الآن سنتعرف على طريقة جديدة ، تمكننا من كتابة ال Comments بأسلوب XML بما يوفر لنا عدة مزايا سنتعرف عليها خلال الدرس .

*** من اوائل اللغات التي طبقت هذه الطريقة كانت **** من خلال ****doc .

يتم ذلك بداية من خلال وضع /// ، بعد وضع هذه العلامة تستطيع وضع أي علامات خاصة بك للكود والذي سيتم التعامل مع لاحقاً على أن XML ما دام يطبق مبادئ XML ، هناك مجموعة من العناصر القياسية التي يفضل استخدامها لتوحيد المفاهيم .

<c> : لتحديد ان اللاحق لا بد أن يعرض بخط مختلف
<code> : لتحديد ان اتعدد الاسطر سيتم التعامل مع ككود
<example> : تحديد مثال لشرح الكود المكتوب
<exception> : الملف الذي يحتوي على الاستثناءات والأخطاء التي يمكن ان تنتج عن هذا الكود أو الفئة
<list> : ادراج قائمة جداول داخل ال ********ation
<param> لشرح بارميتر معين
<permission> وصف وسائل الحماية لجزء معين
<remarks> خيارات ال Build
<returns> وصف ناتج الدالة return;
<see> رابط آخر لجزء آخر من ال ********ation
<seealso> مثل السابق ، ولكن (انظر ايضاً)
<summary> وصف اجمالي للجزء المشروح
<value> لوصف خاصية معينة

والآن ، ما هي الفائدة التي ستجنيها إذا استخدمت هذه الطريقة بدلاً من الطريقة التقليدية ؟؟؟

أولاً ، جرب مثلاً كتابة ما يلي لفئة الموظفين مثلاً :
C#:

كود PHP:


		
			
    /// <summary>

/// Employee Class of the comapny

/// </summary>

    partial class Employee

    {

        /// <summary>

        ///

        /// </summary>

        /// <param name="Firstname">fitst name of the employee</param>

        /// <param name="Lastname">last name of the employee</param>

        /// <param name="age">aqge of the employee</param>

        public Employee(string Firstname, string Lastname, int age)

        {

        }

}

vb.net:

كود PHP:


		
			
''' <summary> 

''' Employee Class of the comapny 

''' </summary> 

Partial Class Employee 

    ''' <summary> 

    ''' 

    ''' </summary> 

    ''' <param name="Firstname">fitst name of the employee</param> 

    ''' <param name="Lastname">last name of the employee</param> 

    ''' <param name="age">aqge of the employee</param> 

 

    Public Sub New(ByVal Firstname As String, ByVal Lastname As String, ByVal age As Integer) 

    End Sub 

End Class

وجرب الآن عمل الكود ، لاحظ الصورة التالية :

http://vb4arab.com/vb/uploaded/3/01218812245.jpg

هل لاحظت الفارق ، اصبح الكود يظهر واضحاً لباقي مبرمجي فريقك ، اليس كذلك ؟

نقطة أخرى : ********ation .

ايضاً ومن ضمن خيارات ال Build ، يمكنك اخراج ********ation كاملة لمشروعك اعتماداً على هذه الوسوم ، لذا من خصائص المشروع قم باختيار Build وقم باختيار انتاج ملف XML بالشكل التالي :

http://vb4arab.com/vb/uploaded/3/11218812245.jpg

جرب الوصول لهذا الملف الذي قمت باختياره ، ستجد شيئاً مثل هذا :

http://vb4arab.com/vb/uploaded/3/21218812245.jpg

نقطة ثالثة : Documenation 2 .

للاسف لا يوفر Visual Studio 2008 اداة افتراضية لتحويل ال XML السابق لصيغة مفهومة ، لكن يمكن استخدام أداة مثل NDoc لتحويل الملف السابق إلى مثل هذه الصورة :

http://vb4arab.com/vb/uploaded/3/31218812245.jpg

كل هذا فقط من ال Comments .

إلى هنا نكون قد انتهينا من محتويات هذا الدرس .

والله الموفق ...
والسلام عليكم ورحمة الله وبركاته .