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