תיעוד

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

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

אני רוצה להבהיר פה משהו שאולי ישמע קיצוני, אבל לא המצאתי אותו בעצמי – עדיף היה לו יכולנו לא לכתוב תיעוד בכלל. למה אני מתכוון? בעולם אידיאלי, הייתי מסוגל לכתוב קוד כל כך ברור, כל כך self descriptive, שכל מילה נוספת היתה מיותרת. הקוד היה מסביר את עצמו. מי שהיה קורא אותו היה מבין מה הוא עושה, ולא הייתי צריך להסביר שום דבר מעבר.

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

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

price = itemPrice * quantity;       // calculates the total price in NIS of quantity items

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

price = itemPrice * quantity * NIS_USD;                // calculates the total price in NIS of quantity items

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

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

אז עצה חשובה להמשך –

השתדלו להמנע מלתעד את המובן מאליו. למשל –

System.out.println(“Hello”);       // prints “hello”

ועל זה אני אומר – וואללה?! לא חבל על המלל?

ועוד משהו חביב:

x++;       // add one to x

אוקי, זה היה ממש נחוץ!

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