תיעוד הקוד (Documentation)

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



תיעוד הקוד (Documentation) 

 
מאת: ארז קלר
 
אלפונס אלה – סופר צרפתי שחי במאה ה-19 אמר פעם שני משפטים שמאוד רלבנטיים למאמר הנוכחי:
  • "זהו חוק בלתי נמנע של האנושות שיש לנו תמיד משהו לא מובן."
  • "יש לי זיכרון נפלא; אני שוכח הכול."
והוא אמר עוד משפט מאוד מפורסם שאפילו יותר רלבנטי למאמר הנוכחי:
"תמיד השארתי למחרתיים מה שיכולתי לעשות לפני יומיים."

סדרת המאמרים הזו עוסקת בטיפוסים ומשתנים, אז מה פתאום תיעוד?

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

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

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

ב- C# קיימים שלושה סוגים של תיעוד:
תיעוד של שורה אחת  - צירוף התווים // (קו אלכסוני כפול)  מסמן למהדר שמדובר בתיעוד של שורה אחת, התיעוד מתחיל מצירוף התווים ומסתיים בסוף השורה.
תיעוד המתפרס על מספר שורות - אם ברצוננו לכתוב תיעוד המתפרס על פני מספר שורות נכתוב את צירוף התווים */ בתחילת התיעוד ואת הצירוף /* בסיומו.
תיעוד למחלקות ומתודות - ישנה גם אפשרות שלישית, מנגנון הרבה יותר מתוחכם ומתקדם הנקרא "תיעוד XML"  המתבסס, איך לא, על XML (ודרך אגב, זו דוגמה מצויינת ששם משמעותי הוא התיעוד הטוב ביותר) ומתחיל בצירוף התווים /// (שלושה קווים אלכסוניים).
בשלב זה ניתן יהיה לתעד רק את המתודה Main.

הדוגמה הקודמת, הפעם עם תיעוד:

 1  : class Program 
 2  : { 
 3  :    /* 
 4  :      תוכנית הדוגמה מדגימה המרה בין טיפוסים שונים 
 5  :      התוכנית מדגימה המרה בין מספרים שלמים למחרוזות וההיפך 
 6  :      ומדגימה המרה בין טיפוסים מספריים שונים 
 7  :     */ 
 8  :     static void Main(string[] args) 
 9  :     { 
 10 :         //הדגמה של המרה בין מספר שלם למחרות נומרית
 11 :         int num = 1234; 
 12 :         string int_str = num.ToString(); 
 13 :         Console.WriteLine("int_str = " + int_str); 
 14 :         // המרה בין מספר ממשי למחרוזת נומרית
 15 :         double dnum = 123.456; 
 16 :         string double_str = dnum.ToString(); 
 17 :         Console.WriteLine("double_str = " + double_str); 
 18 :         // המרה ממחרוזת נומרית למספר שלם
 19 :         int_str = "456"; 
 20 :         num = int.Parse(int_str); 
 21 :         Console.WriteLine("int_str = " + num); 
 22 :         // המרה בין מחרוזת נומרית למספר ממשי
 23 :         double_str = "456.789"; 
 24 :         dnum = double.Parse(double_str); 
 25 :         Console.WriteLine("double_str = " + dnum); 
 26 :         // המרה מ-double ל-int
 27 :         float fnum = 123.345f; 
 28 :         Console.WriteLine("fnum = " + fnum); 
 29 :         // המרה מרומזת
 30 :         short snum = 12345; 
 31 :         num = snum; 
 32 :         Console.WriteLine("num = " + num); 
 33 :         // המרה מפורשת
 34 :         num = 56789; 
 35 :         snum = (short)num; 
 36 :         Console.WriteLine("snum = " + snum); 
 37 :  
 38 :     } 
 39 : } 

הערות:
1. מקובל לכתוב את התיעוד באנגלית, אבל אם יותר נוח לכם בעברית או בערבית, אז תכתבו בעברית או בערבית, תכתבו בכל שפה שתבחרו העיקר שתתעדו.
2. אני בכוונה לא נכנס מה צריך לתעד ואיך לתעד משום שכל מקום עבודה מכתיב תקנים וסטנדרטים משלו.
3. אל תתקמצנו בתיעוד אולם גם אל תגזימו, תיעוד נכון מסביר ומקל, תיעוד קצר ומצומצם מדי אינו עוזר ותיעוד ארוך מידי מעייף ומבלבל.
4. אל תתעדו את המובן מאליו ותתמקדו יותר ב"למה" מאשר ב"איך".

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




 
 



כל הזכויות שמורות למחבר ©