تقييم الموضوع :
  • 0 أصوات - بمعدل 0
  • 1
  • 2
  • 3
  • 4
  • 5
الدرس الواحد والسبعون - XML Commenting
#1
كاتب الموضوع : أحمد جمال

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


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

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

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

C#:

كود :
// here we will do something, set x=startvalue
x = FirstClass.Default();
vb.net:

كود :
' here we will do something, set x=startvalue
x = FirstClass.Default()
الآن سنتعرف على طريقة جديدة ، تمكننا من كتابة ال Comments بأسلوب XML بما يوفر لنا عدة مزايا سنتعرف عليها خلال الدرس .

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

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

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

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

كود :
/// <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:

كود :
''' <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
وجرب الآن عمل الكود ، لاحظ الصورة التالية :


هل لاحظت الفارق ، اصبح الكود يظهر واضحاً لباقي مبرمجي فريقك ، اليس كذلك ؟
}}}
تم الشكر بواسطة:
#3
نقطة أخرى : Documentation .

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


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



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

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


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

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

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



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


يقوم بقرائة الموضوع: بالاضافة الى ( 1 ) ضيف كريم