เขียน commit message ให้ตัวเองในอีกหกเดือนข้างหน้า

คนที่จะเจ็บปวดกับ commit message ห่วย ๆ ไม่ใช่เพื่อนร่วมงาน แต่คือตัวคุณเองตอนตีสองตอนเช้า ที่นั่งไล่ดูว่าบรรทัดนี้ถูกเพิ่มเข้ามาตอนไหน แล้วเจอคำว่า fix

โค้ดบอกว่าทำอะไร คอมมิตต้องบอกว่าทำทำไม

diff บอกเราอยู่แล้วว่ามีการเปลี่ยนอะไรบ้าง สิ่งที่ diff บอกไม่ได้คือเหตุผล คอมมิตที่ดีจึงต้องเล่าส่วนที่หายไปกับข้อความให้

แบบที่ช่วยอะไรไม่ได้:
fix bug

แบบที่ช่วยชีวิตคนอ่าน:
fix(billing): คิด VAT จากยอดหลังหักส่วนลด ไม่ใช่ก่อนหัก

เดิมคำนวณจากราคาเต็ม ทำให้ใบกำกับภาษีแสดง
ยอดสูงกว่าความเป็นจริงเมื่อลูกค้าใช้คูปอง
ตามประกาศกรมสรรพากร ภาษีคิดจากราคาหลังหักส่วนลด

Refs: BILL-482

โครงสร้างที่จำง่ายและใช้กันเยอะ

1. บรรทัดแรก — สรุปสั้น ๆ ไม่เกินประมาณ 70 ตัวอักษร ขึ้นต้นด้วยคำกริยา
2. บรรทัดว่าง — ตัวคั่นเสมอ เครื่องมือหลายตัวใช้ตรงนี้แยกหัวข้อกับเนื้อหา
3. เนื้อหา — อธิบายสาเหตุ ทางเลือกที่เคยพิจารณา และผลกระทบที่อาจเกิด
4. ท้าย — อ้างอิงติคเก็ต เอกสาร หรือคอมมิตที่เกี่ยวข้อง

Conventional Commits ช่วยอะไรได้บ้าง

รูปแบบ type(scope): สรุป ดูเหมือนพิธีกรรม แต่ประโยชน์จริงคือมันทำให้กรองประวัติได้ อยากรู้ว่าอะไรเปลี่ยนในส่วน billing บ้างก็กรองคำเดียว

สิ่งที่ไม่ควรอยู่ในคอมมิต

• การบ่นหรือคำหยาบ ประวัติอยู่ไปอีกนานมาก
• รหัสผ่าน คีย์ หรือข้อมูลส่วนบุคคลของผู้ใช้
• ข้อความที่เข้าใจเฉพาะวันนั้น เช่น "ตามที่คุยกันเมื่อเช้า"

ตกลงกันในทีมดีกว่าหาคำตอบที่ถูกที่สุด

รูปแบบคอมมิตที่ดีที่สุดคือรูปแบบที่ทุกคนใช้เหมือนกันจริง ๆ หมด ถ้าทีมคุ้นกับภาษาไทยก็เขียนไทยได้ ขอแค่อย่าสลับไปมาในไฟล์เดียวกัน

สิ่งที่ช่วยได้มากคือ template ของ git เอง ตั้ง commit.template ไว้ให้มีโครงร่างขึ้นมาทุกครั้ง คนจะเขียนตามโดยอัตโนมัติ