Git commit tôi yêu thích nhất (2019)

 (dhwthompson.com)
3 điểm bởi GN⁺ 2024-02-02 | 1 bình luận | Chia sẻ qua WhatsApp

Git commit tôi yêu thích nhất

  • Bài viết nhấn mạnh tầm quan trọng của thông điệp commit Git và cho rằng đây là một trong những công cụ mạnh mẽ nhất để tài liệu hóa codebase.
  • Tác giả giải thích lý do thông qua ví dụ về commit của lập trình viên Dan Carley có tiêu đề "Convert template to US-ASCII to fix error".
  • Dựa trên kinh nghiệm tại GDS (Government Digital Service), tác giả cho rằng một trong những lợi ích của việc lập trình công khai là có thể chia sẻ những ví dụ như vậy ra ngoài tổ chức.

Vì sao commit này hay

  • Tỷ lệ giữa thông điệp commit và phần thay đổi mã là điều thú vị, nhưng đó không phải là lý do tác giả cho rằng nó đáng để chia sẻ.
  • Nếu ở một tổ chức khác hoặc do một lập trình viên khác viết, thông điệp commit này có thể đã chỉ được tóm tắt là change whitespace hoặc fix bug.
  • Thay vào đó, Dan đã dành thời gian để tạo ra một thông điệp commit thực sự hữu ích cho những người xung quanh.

Giải thích lý do thay đổi

  • Những thông điệp commit tốt nhất không chỉ giải thích đã thay đổi gì mà còn cả vì sao lại thay đổi.
  • Trong commit này, tác giả giải thích chi tiết vì sao bài kiểm thử được thêm vào để khớp nội dung của /etc/nginx/router_routes.conf lại bị lỗi ArgumentError: invalid byte sequence in US-ASCII khi chạy bằng bundle exec rake.
  • Đây là loại thông tin rất đáng để tài liệu hóa, vì nó rất dễ bị mất đi khi mọi người quên mất bối cảnh ban đầu, chuyển sang nhóm khác hoặc rời tổ chức.

Có thể tìm kiếm được

  • Phần đầu của thông điệp commit chứa thông báo lỗi đã dẫn đến thay đổi, vì vậy bất kỳ ai cũng có thể chạy git log --grep "invalid byte sequence" trong codebase hoặc dùng tính năng tìm kiếm commit của GitHub để tìm lỗi này.
  • Trên thực tế, đã có nhiều người tìm kiếm vấn đề này và có thể biết được trước đây ai đã gặp nó, cũng như họ đã xử lý nó như thế nào.

Truyền tải một câu chuyện

  • Thông điệp commit chứa các chi tiết cụ thể về việc vấn đề trông như thế nào, quá trình điều tra diễn ra ra sao và cách nó được giải quyết.
  • Thông điệp commit không chỉ phù hợp để tài liệu hóa một tệp, hàm hay dòng mã cụ thể, mà còn đặc biệt phù hợp để ghi lại thêm thông tin về hành trình mà codebase đã trải qua.

Giúp mọi người thông minh hơn một chút

  • Việc Dan ghi lại các lệnh đã chạy ở từng bước có thể là một cách nhẹ nhàng để chia sẻ kiến thức trong nhóm.
  • Khi đọc thông điệp commit này, ai đó có thể học được một vài mẹo hữu ích về bộ công cụ Unix.
  • Cả người review thay đổi này lẫn người tìm lại commit đó về sau đều có thể học được những điều này.

Xây dựng sự cảm thông và niềm tin

  • Đoạn cuối cùng bổ sung thêm bối cảnh rất con người.
  • Khi đọc nó, bạn có thể cảm nhận được sự bực bội của Dan khi phải mất một giờ để lần theo một lỗi khó chịu, cũng như sự thỏa mãn khi giải quyết xong.
  • Những thông điệp commit như vậy giúp chúng ta nhớ rằng đằng sau mỗi thay đổi đều là một con người đã cố gắng đưa ra quyết định tốt nhất.

Tầm quan trọng của một commit tốt

  • Đây là một ví dụ ở mức cực đoan, và tác giả không kỳ vọng mọi commit đều phải có mức độ chi tiết như thế này.
  • Tuy nhiên, đây là một ví dụ tuyệt vời về việc giải thích bối cảnh đằng sau thay đổi, giúp người khác học hỏi và đóng góp vào mô hình tinh thần tập thể của cả nhóm về codebase.
  • Nếu muốn tìm hiểu thêm về lợi ích của thông điệp commit tốt và các công cụ giúp cấu trúc nó dễ hơn, tác giả gợi ý "Telling stories through your commits" của Joel Chippindale và "A branch in time" của Tekin Süleyman.

Ý kiến của GN⁺

  • Bài viết này nhấn mạnh tầm quan trọng của thông điệp commit Git, đồng thời cho thấy nó có thể trở thành một công cụ mạnh mẽ như thế nào trong việc ghi lại lịch sử của codebase và chia sẻ tri thức.
  • Thông điệp commit của Dan Carley là một ví dụ kiểu mẫu trên nhiều khía cạnh như giải thích lý do thay đổi, khả năng tìm kiếm, truyền tải câu chuyện, chia sẻ kiến thức, và xây dựng sự cảm thông cùng niềm tin.
  • Bằng cách hiểu và thực hành việc viết thông điệp commit tốt, các lập trình viên có thể trải nghiệm sự cộng tác tốt hơn và việc bảo trì mã hiệu quả hơn, từ đó góp phần nâng cao năng suất và hiệu quả của cả nhóm.

Bài viết liên quan

1 bình luận

 
GN⁺ 2024-02-02
Ý kiến trên Hacker News

  • Ý kiến của đồng sáng lập GitHub:

    • Thông điệp commit của Git là một cách độc đáo để ghi tài liệu cho mã nguồn, nhưng chưa được tối ưu hóa.
    • Hầu hết công cụ chỉ hiển thị dòng đầu tiên của thông điệp commit.
    • Git được thiết kế để mọi người tham gia dự án đều có thể đọc thông điệp commit như phần thân email, nhưng trên thực tế gần như không ai xem.
    • Việc dùng git blame để tìm thông điệp commit liên quan cũng rất khó.
    • Thông điệp commit của dự án Git rất chi tiết, nhưng thực tế lại hầu như không được tận dụng.
    • Việc viết tài liệu thật tốt thông qua Git gần như là lãng phí thời gian trong phần lớn cộng đồng.

  • Tầm quan trọng của thông điệp commit đối với các vấn đề cụ thể:

    • Dòng đầu tiên của thông điệp commit, nơi mô tả rõ ràng vấn đề, là rất quan trọng.
    • Khi cần, có thể đọc phần còn lại để lấy thêm thông tin.

  • Cảm nhận cá nhân về thông điệp commit:

    • Có chút tự hào khi viết được một thông điệp commit hay, nhưng không chắc nó có giá trị với người khác hay không.
    • Hầu hết mọi người gần như không bao giờ tìm kiếm thông điệp commit.
    • Một thông điệp commit đẹp có thể chỉ là sự tự mãn của lập trình viên và có thể không mang lại giá trị thực tế.

  • Chiến lược viết dòng đầu tiên của thông điệp commit:

    • Khi dùng git log, dòng đầu tiên là quan trọng nhất.
    • Ở dòng đầu tiên, nên nêu rõ vì sao làm thay đổi đó, chứ không phải đã làm gì.
    • Nên viết theo kiểu bài báo, bắt đầu từ thông tin quan trọng nhất rồi mới đến chi tiết.

  • Sự khó khăn khi chỉnh sửa thông điệp commit:

    • Thông điệp commit rất khó sửa sau khi đã viết.
    • Tài liệu như file .md, wiki hoặc Confluence thì dễ chỉnh sửa hơn.
    • Nên tránh cám dỗ giải thích thiết kế của component trong thông điệp commit, và nếu cần thì hãy cải thiện tài liệu.

  • Tầm quan trọng của giải thích chi tiết cho các commit nhỏ:

    • Commit càng nhỏ thì đôi khi lại càng cần mô tả dài hơn tương đối.
    • Điều quan trọng là phải giải thích chi tiết lý do của những thay đổi nhỏ.

  • Giới hạn của thông điệp commit và vấn đề của công cụ:

    • Cần viết dòng đầu tiên của thông điệp commit cụ thể hơn.
    • Phần mô tả dài còn lại có thể không mang nhiều giá trị.
    • Có ý kiến chỉ ra vấn đề của công cụ phát triển, cho rằng thông báo lỗi nên rõ ràng hơn.
    • Đặt câu hỏi vì sao công cụ chỉnh sửa mã lại cho phép các ký tự khoảng trắng không chuẩn.

  • Tầm quan trọng của vệ sinh commit so với thông điệp commit:

    • So với mức độ chi tiết của thông điệp commit, việc giữ commit sạch sẽ và có tổ chức tốt còn quan trọng hơn.
    • Những commit gọn gàng và độc lập giúp dễ tách xuất và tái sử dụng chức năng của mã.

  • Phê bình auto-squash và rebase:

    • Auto-squash cản trở việc viết các thông điệp commit có ý nghĩa.
    • Rebase là để lập trình viên chủ động dọn dẹp lịch sử, chứ không nên trở thành mẫu mặc định khi merge.