[28 בדצמבר 2007] [6 תגובות]

כל מתכנת העוסק בפיתוח תוכנות מבין את החשיבות של תיעוד הקוד. למרות זאת, מעטים עושים זאת בצורה טובה וברורה.

מיקרוסופט כללה כלי בשם XML Documentation בסביבת הפיתוח DOT NET שאמור לסייע בפיתרון בעיה זאת. על ידי שתילת "תגיות XML" בקוד, ניתן לייצא את התיעוד במספר דרכים:

1. תיעוד IntelliSense
2. יצירת XML והצגתו בדרכים נבחרות שונות

בפוסט זה, ההסברים על תגיות ה-XML נכונים תמיד, אך הדוגמאות לשימוש בהן יוצגו ב-IntelliSense בלבד.

תגיות XML

הערה רגילה בקוד מסומנת על ידי שני לוכסנים(//) ואילו הערות XML מסומנות על ידי שלושה(///). לאחר שלושת הלוכסנים, ניתן להכניס תגיות XML.

נבחן את הדוגמה הבאה (MyMath.cs) :

/// ‹summary›This small math class will teach us XML documentation.‹/summary›
public class MyMath
{
/// ‹summary›String field containing the User's name.‹/summary›
        public string UserName;
/// ‹summary›This method adds two numbers and returns the result.‹/summary›
/// ‹param name="a"›The first number to be added.‹/param›
/// ‹param name="b"›The second number to be added.‹/param›
/// ‹returns›An integer that is the result of the addition.‹/returns›
        public int AddTwoNumbers(int a, int b)
        {
                return a+b;
        }

}

נוכל להציב תג ‹summary›‹/summary› בשורה לפני הגדרת המחלקה(ה-class MyMath), ולכתוב את תיאור המחלקה. ניתן לעשות זאת גם עבור שדות(בדוגמה: UserName) וגם עבור שיטות(AddTwoNumbers).

עבור שיטה, ניתן להכניס תגים מעניינים נוספים:

• ‹param name=a›‹/param› מסביר מהו הפרמטר a שאמור להישלח לפונקצייה
• ‹returns›‹/returns› מסביר מהו הערך שהפונקצייה מחזירה

כך נוכל לתעד כל מחלקה, שדה ושיטה בקוד שלנו.

אז מה יוצא לנו מכל זה ?

כעת השימוש ב-IntelliSense יסביר הכל. IntelliSense היא השיטה של מיקרוסופט להוסיף תיעוד פנימי לתוך סביבת העבודה של Visual Studio. כאשר תגדירו אובייקט חדש על ידי המילה new ובכל פעם שתכתבו שם של אובייקט ותכתבו אחריו נקודה(.), תקבלו תיעוד של כל השדות והשיטות המצויים במחלקה שלו.

דוגמה לפי הקוד שלנו:

תיעוד טוב יאפשר לכם לתחזק את הקוד בקלות למשך זמן.