الدرس الواحد والسبعون : XML Commenting - دورة .net 2008

[khaledbelal]

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

بما أن دروسنا في مجال التطبيقات العامة تقريباً انتهى ، وقبل البدء في عالم 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 


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



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

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

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



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




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

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



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

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

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