สรุปมาจากบทความ 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 ให้ดีกัน เริ่มต้นตั้งแต่วันนี้ยังไม่สายครับ 🙂
