Git commit ที่ฉันชอบที่สุด (2019)

Git commit ที่ฉันชอบที่สุด

• บทความนี้เน้นย้ำความสำคัญของข้อความ commit ใน Git และมองว่านี่คือหนึ่งในเครื่องมือที่ทรงพลังที่สุดในการทำเอกสารให้กับ codebase
• อธิบายเหตุผลผ่านตัวอย่าง commit ของนักพัฒนา Dan Carley ที่มีข้อความว่า "Convert template to US-ASCII to fix error"
• จากประสบการณ์ที่ GDS (Government Digital Service) ผู้เขียนชี้ว่าข้อดีอย่างหนึ่งของการเขียนโค้ดแบบเปิดเผยต่อสาธารณะคือสามารถแบ่งปันตัวอย่างลักษณะนี้กับคนนอกองค์กรได้

ทำไม commit นี้ถึงดี

• สัดส่วนระหว่างข้อความ commit กับการเปลี่ยนแปลงโค้ดนั้นน่าสนใจ แต่ไม่ใช่เหตุผลที่ทำให้คิดว่ามันควรค่าแก่การแบ่งปัน
• ถ้าเป็นองค์กรหรือนักพัฒนาคนอื่น ข้อความ commit นี้อาจถูกสรุปสั้น ๆ แค่ว่า change whitespace หรือ fix bug
• แต่ Dan กลับสละเวลาเพื่อเขียนข้อความ commit ที่มีประโยชน์อย่างมากสำหรับคนรอบตัว

อธิบายเหตุผลของการเปลี่ยนแปลง

• ข้อความ commit ที่ดีที่สุดไม่ได้อธิบายแค่ว่าเปลี่ยน อะไร แต่ยังอธิบายด้วยว่าทำไมถึงเปลี่ยน
• ใน commit นี้ มีการอธิบายอย่างละเอียดว่าทำไมเทสต์ที่ถูกเพิ่มเข้ามาเพื่อให้เนื้อหาของ /etc/nginx/router_routes.conf ตรงกัน จึงล้มเหลวด้วยข้อผิดพลาด ArgumentError: invalid byte sequence in US-ASCII เมื่อรันด้วย bundle exec rake
• ข้อมูลแบบนี้มีคุณค่าสูงมากสำหรับการทำเอกสาร และอาจสูญหายได้ง่ายเมื่อผู้คนลืมบริบทเดิม ย้ายไปทีมอื่น หรือออกจากองค์กร

ค้นหาได้ง่าย

• ตอนต้นของข้อความ commit มี error message ที่เป็นต้นเหตุของการเปลี่ยนแปลง ทำให้ใครก็ตามสามารถรัน git log --grep "invalid byte sequence" ใน codebase หรือใช้การค้นหา commit บน GitHub เพื่อค้นหาข้อผิดพลาดนี้ได้
• ที่จริงแล้วมีหลายคนที่ค้นหาปัญหานี้ และสามารถดูได้ว่าใครเคยเจอปัญหานี้มาก่อนและจัดการกับมันอย่างไร

ถ่ายทอดเรื่องราว

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

ทำให้ทุกคนฉลาดขึ้นอีกนิด

• การที่ Dan บันทึกคำสั่งที่เขารันในแต่ละขั้นตอน อาจเป็นวิธีเบา ๆ ในการแบ่งปันความรู้ภายในทีม
• เพียงแค่อ่านข้อความ commit นี้ ใครบางคนก็อาจได้เรียนรู้เคล็ดลับที่มีประโยชน์เกี่ยวกับชุดเครื่องมือ Unix
• ทั้งคนที่รีวิวการเปลี่ยนแปลงนี้ และคนที่มาเจอ commit นี้ในภายหลัง ต่างก็สามารถเรียนรู้สิ่งเหล่านี้ได้

สร้างความเห็นอกเห็นใจและความไว้วางใจ

• ย่อหน้าสุดท้ายเพิ่มบริบทความเป็นมนุษย์เข้าไป
• เมื่ออ่านข้อความนี้ คุณจะสัมผัสได้ถึงความหงุดหงิดของ Dan ที่ต้องใช้เวลาหนึ่งชั่วโมงไล่ตามบั๊กที่เจ้าเล่ห์ และความพึงพอใจที่ได้แก้ปัญหามันสำเร็จ
• ข้อความ commit แบบนี้ช่วยเตือนให้เราจำได้ว่าเบื้องหลังทุกการเปลี่ยนแปลง มีมนุษย์คนหนึ่งที่พยายามตัดสินใจให้ดีที่สุดอยู่เสมอ

ความสำคัญของ commit ที่ดี

• ตัวอย่างนี้เป็นกรณีสุดขั้ว และไม่ได้คาดหวังว่า commit ทุกอันจะต้องมีรายละเอียดระดับนี้
• แต่มันเป็นตัวอย่างที่ยอดเยี่ยมของการอธิบายบริบทเบื้องหลังการเปลี่ยนแปลง ช่วยให้ผู้อื่นเรียนรู้ได้ และมีส่วนต่อแบบจำลองความเข้าใจร่วมกันของทีมต่อ codebase
• หากอยากรู้เพิ่มเติมเกี่ยวกับประโยชน์ของข้อความ commit ที่ดี และเครื่องมือที่ช่วยให้จัดโครงสร้างมันได้ง่ายขึ้น ขอแนะนำ "Telling stories through your commits" ของ Joel Chippindale และ "A branch in time" ของ Tekin Süleyman

GN⁺ ความเห็น

• บทความนี้เน้นย้ำความสำคัญของข้อความ commit ใน Git และแสดงให้เห็นว่าข้อความ commit สามารถเป็นเครื่องมือที่ทรงพลังเพียงใดในการบันทึกประวัติของ codebase และแบ่งปันความรู้
• ข้อความ commit ของ Dan Carley เป็นกรณีตัวอย่างที่ยอดเยี่ยมในหลายด้าน ทั้งการอธิบายเหตุผลของการเปลี่ยนแปลง ความสามารถในการค้นหา การเล่าเรื่อง การแบ่งปันความรู้ และการสร้างความเห็นอกเห็นใจกับความไว้วางใจ
• การเข้าใจและลงมือปฏิบัติเรื่องการเขียนข้อความ commit ที่ดี จะช่วยให้นักพัฒนาได้สัมผัสกับการทำงานร่วมกันและการดูแลรักษาโค้ดที่ดีขึ้น และยังช่วยเพิ่มผลิตภาพกับประสิทธิภาพของทั้งทีมโดยรวมได้

[GN⁺]

ความคิดเห็นบน Hacker News

• ความเห็นจากผู้ร่วมก่อตั้ง GitHub:

  • ข้อความคอมมิตของ Git เป็นวิธีการจัดทำเอกสารโค้ดที่มีลักษณะเฉพาะ แต่ยังไม่เหมาะที่สุด
  • เครื่องมือส่วนใหญ่แสดงเพียงบรรทัดแรกของข้อความคอมมิต
  • Git ออกแบบข้อความคอมมิตให้ผู้มีส่วนร่วมทุกคนในโปรเจกต์อ่านได้เหมือนเนื้อหาอีเมล แต่ในความเป็นจริงแทบไม่มีใครได้เห็น
  • การใช้ git blame เพื่อค้นหาข้อความคอมมิตที่เกี่ยวข้องก็ทำได้ยาก
  • ข้อความคอมมิตของโปรเจกต์ Git มีรายละเอียดมาก แต่ในทางปฏิบัติแทบไม่ถูกนำมาใช้
  • การเขียนเอกสารอย่างยอดเยี่ยมผ่าน Git สำหรับชุมชนส่วนใหญ่นั้นแทบจะเป็นการเสียเวลา

• ความสำคัญของข้อความคอมมิตต่อปัญหาเฉพาะ:

  • บรรทัดแรกของข้อความคอมมิตที่อธิบายปัญหาได้อย่างชัดเจนมีความสำคัญ
  • หากจำเป็น ก็สามารถอ่านส่วนที่เหลือเพื่อดูข้อมูลเพิ่มเติมได้

• ความรู้สึกส่วนตัวต่อข้อความคอมมิต:

  • แม้จะภูมิใจกับการเขียนข้อความคอมมิตที่ยอดเยี่ยม แต่ก็ไม่มั่นใจว่ามันมีคุณค่าต่อผู้อื่นหรือไม่
  • คนส่วนใหญ่แทบไม่ค้นหาข้อความคอมมิต
  • ข้อความคอมมิตที่สวยงามอาจเป็นเพียงความทะนงของโปรแกรมเมอร์ และอาจไม่มีคุณค่าในทางปฏิบัติ

• กลยุทธ์การเขียนบรรทัดแรกของข้อความคอมมิต:

  • เมื่อใช้ git log บรรทัดแรกคือส่วนที่สำคัญที่สุด
  • บรรทัดแรกไม่ควรระบุแค่ว่าทำอะไร แต่ควรระบุว่าทำไปทำไม
  • ควรเขียนแบบข่าว โดยเรียงจากข้อมูลที่สำคัญที่สุดไปยังรายละเอียดเพิ่มเติม

• ความยากในการแก้ไขข้อความคอมมิต:

  • ข้อความคอมมิตแก้ไขได้ยากหลังจากเขียนไปแล้ว
  • เอกสารอย่างไฟล์ .md, วิกิ หรือ Confluence แก้ไขได้ง่ายกว่า
  • ควรหลีกเลี่ยงการอธิบายการออกแบบของคอมโพเนนต์ในข้อความคอมมิต และหากจำเป็นควรปรับปรุงเอกสารแทน

• ความสำคัญของคำอธิบายละเอียดสำหรับคอมมิตเล็ก ๆ:

  • ยิ่งเป็นคอมมิตเล็ก ก็อาจยิ่งต้องการคำอธิบายที่ยาวขึ้นเมื่อเทียบกัน
  • การอธิบายเหตุผลของการเปลี่ยนแปลงเล็ก ๆ อย่างละเอียดเป็นสิ่งสำคัญ

• ข้อจำกัดของข้อความคอมมิตและปัญหาของเครื่องมือ:

  • จำเป็นต้องเขียนบรรทัดแรกของข้อความคอมมิตให้เจาะจงมากขึ้น
  • คำอธิบายยาว ๆ ที่เหลืออาจไม่ได้มีคุณค่ามากนัก
  • มีการชี้ปัญหาของเครื่องมือพัฒนา และมองว่าข้อความแสดงข้อผิดพลาดควรชัดเจนกว่านี้
  • ตั้งคำถามว่าทำไมเครื่องมือแก้ไขโค้ดจึงยอมให้มีอักขระช่องว่างแบบไม่เป็นมาตรฐาน

• ความสำคัญของสุขอนามัยคอมมิตมากกว่าข้อความคอมมิต:

  • สุขอนามัยของคอมมิตที่ดีสำคัญกว่าความละเอียดของข้อความคอมมิต
  • คอมมิตที่สะอาดและเป็นอิสระต่อกันช่วยให้ดึงและนำความสามารถของโค้ดกลับมาใช้ใหม่ได้ง่าย

• คำวิจารณ์ต่อ autosquash และ rebase:

  • autosquash ขัดขวางการเขียนข้อความคอมมิตที่มีความหมาย
  • rebase มีไว้ให้นักพัฒนาจัดระเบียบอย่างตั้งใจ ไม่ควรกลายเป็นรูปแบบมาตรฐานโดยปริยายตอน merge