הערות/תיעוד - Comments

הערות בקוד, זה כלי מאוד מפתה. 

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

אבל יש בעיה עם הערות. הערות גורמות לעומס על הקוד.

במקום לכתוב קוד שניתן להבין בקלות נתקעים על סנכרון בין ההערות לבין הקוד.

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

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

או אפילו שהפונקציות היו גדולות מדי ובעלות כמה תפקידים. והוא פשוט התייאש.

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

אם מישהו מגיע למצב שהוא צריך לכתוב הערה הוא, אותו אדם צריך לשאול את עצמו איך אני כותב את הקוד טוב יותר כדי שרק מקריאה של הקוד יבינו את המשמעות של ה"משפט" שכתבתי כרגע?

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

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

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

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

יש רק מספר מקומות בהם לדעתי חובה לרשום הערות:
1) תיעוד של INTERFACES

2) אם צריך להכניס todo לצורך refactor עתידי.

סוג מאוד לא נחוץ של הערות שלפעמים מתכנתים נוקטים בו הוא הערות על Properties שמסבירים את עצמם, או סתם רעש לדוגמא:

    public class Person

    {

        //Default Constructor

        public Person()

        {

        }

        // the Date of birth of the Person

        public DateTime DateOfBirth { get; set; }

        //  the first name of the Person

        public string FirstName { get; set; }

        // the last name of the Person

        public string LastName { get; set; }

        // the address of the Person

        public string Address { get; set; }

        //List of friends

        public List<Person> Friends { get; set; }

        // Returns the age of the Person

        public double Age

        {

            get

            {

                if (DateOfBirth == null ) return 0;

                return (DateTime.Now - DateOfBirth).TotalDays/365;

            }

        }

    }

השאלה היא פשוטה, למה לרשום הערות למשהו שהוא מראש מסביר את עצמו?

ההערות האלו מבלבלות ומסיחות את הדעת מהקוד שהוא ברור מאליו.

או למשל ההערה שה-Constructor הוא דיפולטי, זה ברור מאליו, לא?

בכל זאת יש מתכנתים בעיקר צעירים שמרגישים צורך לתעד כל שורה בקוד.

דוגמא נוספת להערות שהיום הם פשוט רעש אלו הערות ה"לוח שינויים".

פעם שלא היה ממש Source Control, למשל בסביבות ישנות של- C או NATURAL/Cobol,

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

מה עוד שעד שהגענו לקוד היינו צריכים לגלול דפים על גבי דפים.

היום אין צורך בזה משום שכל Source Control שמכבד את עצמו כבר מכיר תיעוד על כל נגיעה בקוד ומי בדיוק ביצע את השינוי ומה היה לפני זה.

הלוג הזה היה נראה משהו כמו:

/* Changes Log

 * =====================================================================

 * RK001 - 2009/7/1 - Bug Fix in Person Name

 * RK002 - 2009/8/1 - Refactor in Person

 * RK003 - 2010/1/1 - added method AddFriend(otherPerson)

 * RK004 - 2010/2/1 - added method UnFriend(perosn);

 * RK005 - 2010/3/1 - some bug fixes

 */

עם כל מיני קישקושים בקוד של מי ביצע (RK001)

ועל כל שינוי היינו צריכים לרוץ לתחילת הקובץ

 אם היום אתם עדיין מתעדים ככה, ותרו. הוא מיותר בסביבת קוד מנוהלת – Source Controlled.