Viết commit message chuẩn cho dev: quy tắc thực tế
Một commit message tốt trả lời được câu hỏi: sáu tháng sau, khi ai đó chạy git blame lên dòng code này, họ có hiểu vì sao nó tồn tại không? Bài này chỉ cho bạn cách viết message rõ ràng, nhất quán, để lịch sử Git trở thành tài liệu sống thay vì một đống “fix bug”, “update”, “asdf”. Bạn sẽ có cấu trúc chuẩn, quy ước đặt tên và checklist áp dụng ngay hôm nay.
Vì sao commit message quan trọng hơn bạn nghĩ
Code nói cho bạn biết chuyện gì đang xảy ra. Commit message nói cho bạn biết vì sao nó xảy ra. Cái “vì sao” đó không nằm trong code, và nó biến mất khỏi trí nhớ chỉ sau vài tuần.
Khi lịch sử commit sạch, bạn được ba thứ: review nhanh hơn vì reviewer hiểu ý định, debug dễ hơn vì git bisect chỉ đúng commit gây lỗi kèm lý do, và onboarding người mới nhẹ nhàng hơn vì họ đọc được mạch tư duy của cả đội.
Cấu trúc một commit message tốt
Dòng tiêu đề (subject)
Ngắn gọn, dưới khoảng 50 ký tự, viết ở thể mệnh lệnh: “Thêm”, “Sửa”, “Xóa” thay vì “Đã thêm” hay “Đang sửa”. Mẹo kiểm tra: câu “Nếu áp dụng, commit này sẽ…” phải nối liền mạch với tiêu đề của bạn.
Phần thân (body)
Không bắt buộc, nhưng cần khi thay đổi phức tạp. Cách dòng tiêu đề một dòng trống. Tập trung vào vì sao và bối cảnh, không lặp lại cái mà diff đã hiển thị rõ. Ví dụ: “Cache cũ không invalidate khi user đổi email, gây gửi sai địa chỉ. Chuyển sang invalidate theo key user_id.”
Quy ước Conventional Commits
Nhiều đội dùng tiền tố dạng feat:, fix:, refactor:, docs:, test:, chore:. Lợi ích: máy đọc được để sinh changelog và tự động tăng version. Đây là một quy ước phổ biến, không phải luật; hãy thống nhất trong đội trước khi ép dùng.
Ví dụ thực tế
So sánh hai cách ghi cùng một thay đổi:
| Kém | fix login |
| Tốt | fix: chặn đăng nhập khi token hết hạn |
Với phần thân đầy đủ, commit “tốt” sẽ có thêm: “Trước đây token hết hạn vẫn cho vào dashboard vì middleware chỉ kiểm tra token tồn tại, không kiểm tra thời hạn. Bổ sung so sánh exp với thời gian hiện tại. Ảnh hưởng: user có session cũ sẽ bị buộc đăng nhập lại.” Reviewer đọc xong hiểu ngay rủi ro mà không cần hỏi.
Lỗi thường gặp và cách sửa
Gộp quá nhiều thứ vào một commit
Một commit vừa sửa bug, vừa đổi tên biến, vừa thêm tính năng thì không thể revert riêng lẻ. Cách sửa: tách theo ý định. Dùng git add -p để chọn từng đoạn thay đổi đưa vào các commit khác nhau.
Message chỉ nói “cái gì” mà bỏ “vì sao”
“Đổi timeout thành 30s” không giúp ai. “Đổi timeout thành 30s vì API bên thứ ba thường phản hồi 20-25s khi tải cao” mới có giá trị. Cách sửa: luôn tự hỏi lý do trước khi commit.
Commit dở dang, code không chạy được
Mỗi commit nên là một trạng thái hoạt động được, để git bisect còn dùng được. Cách sửa: chỉ commit khi build và test cơ bản đã xanh.
Checklist trước khi commit
- Tiêu đề dưới 50 ký tự, thể mệnh lệnh, không dấu chấm cuối câu
- Một commit chỉ giải quyết một việc rõ ràng
- Phần thân giải thích vì sao, nếu thay đổi không hiển nhiên
- Đã chạy git diff –staged để xem lại đúng những gì mình đưa vào
- Không lẫn file rác, khóa bí mật hay debug print
- Code ở trạng thái build và test được
Kết luận và bước tiếp theo
Commit message tốt là khoản đầu tư rẻ nhất mà bạn có thể làm cho tương lai của cả đội. Bước tiếp theo: thống nhất với đội một quy ước ngắn gọn, ghi vào file CONTRIBUTING, và cân nhắc thêm một commit hook đơn giản để nhắc kiểm tra định dạng tiêu đề.
Câu hỏi thường gặp
Nên viết commit message bằng tiếng Việt hay tiếng Anh?
Tùy đội. Nếu tất cả thành viên đều là người Việt và dự án nội bộ, tiếng Việt không dấu hoặc có dấu đều được. Nếu dự án open source hay có người nước ngoài, dùng tiếng Anh. Quan trọng là nhất quán trong cùng một repo.
Commit nhỏ và nhiều có tốt hơn commit lớn không?
Thường là có, vì dễ review và dễ revert. Nhưng đừng nhỏ đến mức mỗi dòng một commit. Nguyên tắc: một commit là một thay đổi logic hoàn chỉnh, tự đứng vững được.
Có nên squash các commit trước khi merge?
Squash hữu ích khi nhánh feature có nhiều commit dạng “sửa theo review” gây nhiễu. Squash lại thành vài commit ý nghĩa giúp nhánh main sạch. Nhưng đừng squash mất bối cảnh cần thiết của những thay đổi lớn.
Làm sao sửa message của commit đã lỡ viết sai?
Nếu là commit gần nhất và chưa push, dùng git commit –amend. Với các commit cũ hơn thì rebase tương tác. Lưu ý: không sửa lịch sử đã push lên nhánh chung mà người khác đang dùng.
Nguồn tham khảo
- Pro Git (Scott Chacon, Ben Straub) — sách chính thức về Git
- Conventional Commits — quy ước phổ biến về định dạng commit
- Bài viết “How to Write a Git Commit Message” của Chris Beams
