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

$ git log --oneline -10

מי שעובד לבד על הפרויקט אולי יכול להיזכר מה כל הודעה אומרת (כי הוא כתב אותה) וגם זה לא תמיד. ומי שעובד בצוות בכלל בצרה.

אז מה מבדיל בין הודעת קומיט טובה לגרועה? אני חושב שהודעה טובה צריכה לעבור 3 מבחנים:

1. היא מסבירה מה השינוי שבוצע
2. היא מסבירה למה ביצענו את השינוי
3. היא לא מבלבלת

נתחיל עם הסעיף השלישי כי אותו הכי קל להבין.

1. הודעת קומיט צריכה להיות לא מבלבלת

מצאתי לא מזמן את ההודעה הזאת בגיט לוג שלי:

a53a102 FIXED typo

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

 2 files changed, 51 insertions(+), 60 deletions(-)

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

-      f.input :screencast, colleciton: Screencast.tagged_with('workshop')
+      f.input :screencast, collection: Screencast.tagged_with('workshop')

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

דוגמא אחרת מהעולם הגדול היא הקומיט הבא מתוך פרויקט 2048 שמימש את משחק 2048 ב C++:

038e1 add vim bindings support

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

במינימום הודעת commit צריכה לא לבלבל: היא צריכה לספר מה השתנה ולמה ואם אפשר לתאר את ה context של השינוי.

2. הודעת קומיט צריכה להסביר מה השינוי שבוצע

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

בלוג הקומיטים של ריאקט מצאתי את ההודעה:

0f050 Make regression test better

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

סוג נוסף של הודעות חסרות ערך הוא הודעות שאומרות איזה קבצים שיניתם. כך לדוגמא מתוך הפרויקט React On Rails:

ea9d8 Update README.md

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

$ git log --name-only --oneline

לכן לציין שעדכנתם קובץ X או Y זה בזבוז זמן.

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

ea9d8 Add shakacode contact details to readme file

3. הודעת קומיט צריכה להסביר למה עשינו את השינוי

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

בפרויקט raspotify מצאתי את ההודעה הבאה:

01cd8 Use most recent version of rust

ומיד שאלתי - למה? איזה גירסת rust הותקנה קודם? ולמה לא לבחור גירסא שאתה יודע עובדת?

נשווה את זה להודעה הבאה מתוך הלוג של שפת התכנות Julia:

commit 48c68467a457d83b64b7342b324404b2b3d88adb

    Fix a small typo in sroa

    This caused the optimizer to miss some optimization opportunities.

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

קישור כזה אפשר למצוא בהודעת הקומיט הבאה מתוך פרויקט vim-surround:

commit e49d6c2459e0f5569ff2d533b4df995dd7f98313

    Only add colon if prompt ends with word (#204)

    Lets you use your own ending characters, instead of always adding ': '.

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

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