การเขียน Git Commit Message

การเขียน Git Commit Message

สรุปมาจากบทความ How to Write a Git Commit Message ของ Chris Beams นะครับ ตามไปอ่านฉบับเต็มๆ กันได้

การเขียน commit message นั้นสำคัญมาก เพราะว่ามันเป็นอีกช่องทางการสื่อสารหนึ่งระหว่างโปรแกรมเมอร์ด้วยกัน และยังเป็นช่องทางที่ดีที่สุดในการบอก context ของการแก้โค้ดนั้นๆ อีกด้วย การเขียน commit message นั้น ควรจะเป็นข้อตกลงของทีม เป็นสิ่งที่ทุกคนควรจะร่วมแรงร่วมใจกันทำนะครับ

Peter Hutterer หนึ่งใน senior software engineer บริษัท Red Hat ได้กล่าวไว้อย่างน่าสนใจว่า

Re-establishing the context of a piece of code is wasteful. We can't avoid it completely, so our efforts should go to reduce it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

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

โปรเจคระยะยาวต้องการการดูแลรักษาที่ดี การดูแลรักษา log ของเรานั้นเป็นสิ่งจำเป็น และคุ้มค่า Chris เค้าได้กล่าวถึง 7 กฎพื้นฐานง่ายๆ ในการดูและรักษาประวัติศาสตร์ของเรา เราไปดูทีละข้อกัน

1. แยก subject กับ body ด้วย blank line

ตัวอย่างเช่น

Introduce a new method called print_hello_world

This method prints "Hello World" when the application starts. Bla bla bla..
เวลาที่เราสั่ง git log เราจะเห็นข้อความทั้งหมด แต่เวลาที่เราสั่ง git log --oneline เราจะเห็นแค่ส่วน subject ครับ ให้เราเขียนสรุปย่อๆ ของ commit นั้นๆ พอ ส่วนของ body เราก็ลงรายละเอียดเกี่ยวกับ commit นั้นๆ (เราให้กำหนด wrap ตัวอักษรไว้ด้วย อาจจะตั้งไว้ว่าไม่เกิน 72 ตัวอักษร)
จริงๆ แล้วถ้าเราเขียน subject ได้สรุปครอบคลุมแล้ว ส่วน body ก็ไม่จำเป็นนะครับ

2. subject ไม่เกิน 50 ตัวอักษร

เขียนพอให้ได้ใจความสรุปสั้นๆ ให้ได้ใจความพอครับ ถือว่าเป็นการฝึกคิดไปในตัว (เรื่องจำนวนตัวอักษรอาจจะกำหนดสูงสุดไว้ที่ 69 ตัวอักษรก็ได้)

3. ให้อักษรตัวแรกของ subject เป็นตัวใหญ่

สำหรับผมแล้ว เวลาที่เราดู log เราจะอ่านง่ายกว่าเวลาที่ตัวอักษรตัวแรกของ subject เป็นตัวเล็กครับ

4. ไม่ต้องปิดท้ายประโยคด้วยจุด

เนื่องจากเราจะตัดสิ่งที่ไม่จำเป็นออก แล้วก็ต้องประหยัดจำนวนตัวอักษร มีหรือไม่มีจุดปิดท้ายประโยคก็ไม่ได้ทำให้ข้อความมีความหมายต่างออกไป ตัดออกเลย

5. ใช้ประโยคคำสั่งในส่วน subject

เช่น Clean print_hello_world method หรือ Add query for non-member ที่ใช้แบบนี้ก็เพราะจะได้เป็น convention เดียวกับ Git เนื่องจาก Git ก็ใช้ประโยคคำสั่งเช่นกันครับ เช่น Merge branch 'myfeature' หรือ Rever "Add small thing"

Chris เค้าได้แนะนำการเขียนส่วน subject ไว้ว่าให้ลองประกอบประโยคนี้

If applied, this commit will your subject line here

ถ้าเราเอาส่วน subject เรามาใส่แล้วอ่านแล้วสามารถเข้าใจได้ subject นั้นก็ถือว่าโอเคครับ

6. body ให้ wrap ไม่เกิน 72 ตัวอักษรต่อบรรทัด

ทำแบบนี้แล้วจะทำให้ commit message เราอ่านง่ายขึ้นครับ ดูเป็นระเบียบ ลองนึกถึงประโยคยาวๆ ที่ไม่โดน wrap เทียบกับประโยคยาวๆ ที่โดน wrap สิครับ อันไหนน่าอ่านกว่ากัน

7. ใช้ส่วน body อธิบาย what why และ how

ลองดูตัวอย่าง commit ของ Bitcoin ครับ

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <[email protected]>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

ดูดีเลยทีเดียว

เรามาเขียน commit message ให้ดีกัน เริ่มต้นตั้งแต่วันนี้ยังไม่สายครับ 🙂

หมายเหตุ บทความต้นฉบับผมเขียนไว้ที่เว็บสมาคมโปรแกรมเมอร์ไทย ขอเอามาลงไว้ที่นี่ด้วยเพื่อให้น้องๆ ในทีม หรือน้องๆ ที่เข้ามาใหม่ได้อ่านกัน


Kan Ouivirach

Kan Ouivirach

Lead Software Architect

Being interested in Agile software development, I joined an Agile team at Pronto Tools as a Research & Development Architect (as Lead Software Architect now). I am an enthusiastic architect who not only has a scientific mindset, but also a practical approach to software solutions.