Hãy giữ phần mô tả code thật đơn giản

• Trong code review, khi phần giải thích dài đi kèm với diff lớn, người review sẽ khó nắm được lý do thay đổi cốt lõi, vì vậy commit message, mô tả merge request và comment nên ngắn gọn
• Phần giải thích nên tập trung vào vì sao thay đổi hơn là thay đổi gì, vì nhiều nội dung chỉnh sửa có thể được thấy ngay trong chính code
• Những phần mô tả dài cố gắng nhồi nhét toàn bộ ngữ cảnh cùng lúc có thể làm giảm mức độ tập trung và tốc độ review của một số người
• Trong review trước khi merge, commit mang tính nguyên tử đặc biệt quan trọng; các chỉnh sửa nhỏ có thể xử lý bằng git amend, còn việc dọn dẹp trước khi hợp nhất có thể làm bằng rebase hoặc squash
• Ngay cả khi dùng công cụ LLM, việc tự viết comment, phần mô tả và commit message vẫn hữu ích hơn cho việc hiểu code và giúp người review dễ tiếp cận hơn

---

Mô tả review nên tập trung vào “vì sao” hơn là “cái gì”

• Trong code review, nếu phần giải thích, commit và merge request chứa quá nhiều thông tin, gánh nặng cho người review sẽ tăng lên
• Thay vì liệt kê dài dòng các thay đổi, điều quan trọng là viết rõ vì sao đã thay đổi
• Bản thân code có thể cho thấy phần lớn các thay đổi, và nếu thiếu ngữ cảnh thì reviewer có thể đặt câu hỏi
• Những phần mô tả được viết dài như một bài văn có thể khiến việc review chậm hơn với những người khó tập trung
• Commit message, mô tả merge request và comment trong code nên rõ ràng, đi thẳng vào ý chính và chỉ chứa thông tin cần thiết

Yêu cầu về việc sắp xếp commit và sử dụng LLM

• Commit trong review trước khi merge nên đặc biệt mang tính nguyên tử, và mỗi thay đổi cần có thể được hiểu một cách độc lập
• Các chỉnh sửa nhỏ có thể phản ánh bằng git amend, và trước khi hợp nhất có thể sắp xếp lại bằng rebase hoặc squash
• Ngay cả khi dùng công cụ LLM, tác giả cho rằng vẫn nên tự viết comment, phần mô tả và commit message
  • Quá trình tự viết giúp hiểu rõ nội dung thay đổi hơn
  • Phần mô tả do tự viết có thể dễ tiếp cận hơn với reviewer
• Bài viết cũng kèm quan điểm cá nhân rằng nếu có thể thì nên tránh dùng công cụ LLM
• Dù có phản hồi về cách dùng từ “khả năng tiếp cận”, trọng tâm vẫn là đề nghị làm cho phần mô tả trong code review ngắn gọn hơn và dễ xem xét hơn

[GN⁺]

Ý kiến trên Lobste.rs

• Cần cẩn thận khi đồng nhất yêu cầu trợ năng với sở thích cá nhân của một người cụ thể
  Có ADHD không đồng nghĩa với việc ghét commit message dài là một đặc điểm phổ quát của ADHD, và trợ năng không phải là “làm mọi thứ theo ý người có ADHD”, mà gần hơn với những điều chỉnh hợp lý không gây gánh nặng quá mức cho người dùng nói chung
  Vì vậy nhiều tính năng trợ năng thường được đặt sau các thiết lập mà mỗi người có thể tự chọn, như độ tương phản cao, giảm hiệu ứng chuyển động, hay dark mode

  • Có lẽ tôi nên viết rõ hơn, nhưng AuDHD của tôi cần một số điều kiện nhất định để có thể làm việc và hoạt động bình thường
    Những khối văn bản dài, chẳng hạn giải thích dài tới hai trang A4 cho một thay đổi nhỏ, có thể làm công việc bị chặn hoàn toàn, và nếu cố đọc hết thì dễ dẫn tới kiệt sức
    Có lẽ tôi nên diễn đạt theo kiểu “đây là nhu cầu trợ năng của tôi, và tôi biết có nhiều người tương tự”
    Dù vậy, người khác cũng có thể xem đây là sở thích chứ không phải yêu cầu, nhưng khi gắn những bức tường chữ do LLM tạo ra vào commit message thì mong mọi người cũng nghĩ tới những người như tôi
  • Mỗi người mỗi khác, nhưng “hãy nói trọng tâm trước” theo tôi đúng là một đặc trưng cốt lõi của ADHD ở mức khá cao
    Về mặt trợ năng, ai cũng hưởng lợi từ kiểu điều chỉnh này nên tôi không thấy có lý do gì để phản đối
  • Theo kinh nghiệm của tôi, phần lớn những khó khăn không cần thiết mà người đa dạng thần kinh và người khuyết tật gặp phải bắt nguồn từ việc xem nhu cầu trợ năng như sở thích cá nhân
    Khi trợ năng được cải thiện, ngay cả những người không nhất thiết cần tính năng đó để đứng trên cùng một vạch xuất phát cũng vẫn được hưởng lợi, nên đi theo hướng đó là điều tốt

• Từ trước thời AI tôi đã luôn thích chú thích quá chi tiết, và nhiều người từng làm việc cùng tôi cũng thấy khá ngạc nhiên
  Ví dụ có phương thức này: https://github.com/ghostty-org/ghostty/…
  Trong 15 năm qua, bất kể ngôn ngữ nào, tôi nhìn chung đều viết theo phong cách này, và trong thời đại AI tôi còn ghi rõ cách làm đó trong AGENTS.md
  File được link và toàn bộ chú thích đều do con người viết, hoàn toàn không dùng AI
  Lý do rất đơn giản: nó ép tuân theo quy tắc ghi chép kép là chú thích và code phải khớp nhau
  Nếu hai thứ không khớp thì hoặc chú thích sai, hoặc code sai, hoặc cả hai đều sai, và chỉ riêng câu hỏi “rốt cuộc cái nào đúng?” cũng đã giúp bắt ra rất nhiều vấn đề
  Cuối cùng thì nếu là dự án của riêng mình, ai cũng có thể chú thích theo cách mình muốn

  • Tôi cũng thỉnh thoảng bị đùa vui rằng viết chú thích còn nhiều hơn viết code, nhưng tôi thật sự rất thích kiểu chú thích này
    Khi đọc lại code về sau, nó giúp giữ lại bối cảnh của những quyết định cục bộ mà tôi đã đưa ra lúc đó, đồng thời cũng giúp reviewer hay người mới nhìn lần đầu xây dựng được bối cảnh
    Loại chú thích này có thể dài dòng, nhưng không phải kiểu “chi tiết thừa thãi” mà bài viết đang nói tới, và ví dụ được chia sẻ có vẻ là một minh họa tốt cho câu châm ngôn “đừng giải thích cái gì, hãy giải thích vì sao”
  • Những chú thích như vậy là rất tuyệt
    Như ví dụ đã nêu, chú thích giải thích vì sao người dùng macOS lại đưa cấu hình shell vào ~/.bash_profile và kỳ vọng login shell sẽ đọc nó sẽ cung cấp bối cảnh hữu ích về việc tại sao một quyết định cụ thể được đưa ra
    Nhưng quay lại với LLM thì cá nhân tôi vẫn chưa từng thấy chú thích do LLM tạo ra nào đạt chất lượng như vậy
    Thường thì chúng chỉ lặp lại những điều quá hiển nhiên mà chỉ cần đọc code là biết, kiểu làm foo(), rồi làm bar(), cuối cùng làm baz
  • Kiểu chú thích được link ở trên thì không có vấn đề gì
    Vấn đề là cái cảnh hỗn loạn khi chỉ một thay đổi rất nhỏ mà cũng đính kèm bảng biểu khổng lồ và danh sách gạch đầu dòng
  • Mức độ chi tiết như vậy quả thật rất đáng trân trọng, nhưng cá nhân tôi vẫn thích nó nằm trong commit message của commit thêm phương thức đó hơn là trong chú thích
    Commit message sẽ luôn là bản ghi gắn với đúng thời điểm của code, còn chú thích thì theo tôi có thể dần lệch đi theo thời gian
  • Phần chú thích bắt đầu từ dòng 1467 là một kiệt tác, cảm giác mệt mỏi hiện rõ trong đó

• Ở chỗ làm, tôi đã thử lịch sự ghi trong mẫu PR rằng “hãy trực tiếp giải thích động cơ của thay đổi này và những quyết định thiết kế quan trọng mà reviewer cần chú ý”
  Thế nhưng 9 trên 10 lần, LLM đang được dùng lúc đó lại xóa sạch toàn bộ template, rồi phun ra một đoạn giải thích dài lê thê kèm số lượng test đã thêm, checkbox pass, và những nhánh lan man dài dòng về các chi tiết vụn vặt
  Nhờ vậy mà việc review trở nên cực kỳ thú vị

  • Ở chỗ tôi cũng có đúng vấn đề đó
    Không rõ ai nghĩ rằng nhét công cụ tạo commit message bằng LLM vào khắp nơi là ý hay, nhưng kết quả là vấn đề https://noslopgrenade.com/ xuất hiện ngay trong commit
    Commit message hay mô tả pull request không còn bối cảnh hữu ích như động cơ thay đổi, quyết định thiết kế hay căn cứ lý do, mà bị biến thành những đoạn văn diễn giải chi tiết triển khai vốn chỉ cần đọc code là biết
  • Tôi cũng đã thấy kiểu hành xử đó
    Tôi đang nghĩ tới việc thêm vào agents.md dòng “khi viết commit message thì hãy tham khảo commit-messages.md”
    Trong commit-messages.md có thể đưa vào hướng dẫn viết commit message như cấm checkbox test pass/fail, tóm tắt các test thay vì liệt kê từng cái, hoặc thậm chí không cần ghi test ra

• Tôi chỉ viết chú thích về việc mình đang làm gì khi tôi không chắc cách đó có đúng hay không, chứ không phải để giải thích vì sao làm vậy
  Nguồn gốc gây đau khổ lặp đi lặp lại điển hình là regex

  • Tôi cũng thế
    Có lúc đúng là phải giải thích thật chắc chắn mọi thứ, nhưng dạo này tôi thấy ngay cả những thay đổi nhỏ như đổi tên biến cũng bị gắn kèm một bài giải thích khổng lồ

• Điều thú vị là tôi lại thường xuyên bị chê rằng commit message của mình quá ngắn

  • Cuộc thảo luận trong bài này đặt cạnh hướng ngược lại, tức là bài Chesterton middle finger phàn nàn rằng giải thích quá ngắn
  • Có thể quá ngắn thật, nhưng nhét cả một cuốn tiểu thuyết vào đó cũng vô lý không kém
  • LLM thật sự viết quá nhiều
    Vì vậy tôi đã cấu hình để claude tuyệt đối không được viết chú thích, vì tôi toàn phải tự xóa 98% rồi viết lại nốt 2% còn lại anyway

• Tôi thường thích các commit message rất giàu tính diễn giải, nhưng lại có xu hướng sắp xếp theo cấu trúc kiểu bài báo: đưa thông tin quan trọng nhất lên trước, rồi đặt các chi tiết kém quan trọng hơn nhưng vẫn liên quan ở phía sau
  Ví dụ, tiêu đề nên chứa thông tin quan trọng nhất với mật độ cao nhất có thể; đoạn đầu giải thích thay đổi bằng câu chữ ít nén hơn; còn các đoạn sau để thêm chi tiết mà không cần đọc kỹ trừ khi thật sự khó hiểu bản chất của thay đổi trong mã
  Có vẻ tầm quan trọng của commit message đối với những người sẽ đọc mã về sau đang bị đánh giá thấp
  Khi đào sâu codebase và tự hỏi vì sao một khối mã lại trông như vậy, tôi chưa bao giờ thấy thất vọng khi git blame dẫn tới một commit message giải thích cực kỳ chi tiết rằng thứ đang trông có vẻ vụng về đó thực ra là lựa chọn còn sót lại sau nhiều cách tiếp cận khác nhìn qua thì có vẻ tốt hơn nhưng đều chưa hoàn chỉnh
  Quay lại ý chính của tác giả, việc thêm các dấu hiệu tường minh vào giao tiếp là một điều chỉnh tốt và nhìn chung cũng hữu ích
  Bạn có thể chèn vào giữa commit message một câu như “nếu bạn đang review đoạn mã này thì có thể dừng đọc ở đây”

• Câu “chi tiết không cần thiết thì khi cần có thể hỏi” là một giả định khá táo bạo rằng người đó sẽ luôn còn ở quanh đây
  Tôi bắt đầu chăm chút viết commit message khi bắt đầu đóng góp cho một codebase FLOSS đã hơn 10 năm tuổi
  Cách duy nhất để tìm hiểu thêm vì sao mã lại tồn tại theo cách đó là làm git archaeology, và tôi đã học vc-annonate của Emacs để lần theo dễ hơn
  Ngay cả trong mã ở công ty, cũng đã nhiều lần tác giả ban đầu của codebase mà tôi bảo trì rời đi từ rất lâu rồi
  Commit message không chỉ được đọc trong lúc review, mà thực tế nhiều UI review còn ẩn commit message đi
  Vấn đề có vẻ không nằm ở commit message dài, mà gần hơn với commit message được viết dở
  Hướng dẫn kiểu “commit message, mô tả merge request và chú thích mã nên được viết rõ ràng, đi thẳng vào trọng tâm theo nhu cầu, và giải thích tại sao chứ không phải cái gì” nghe khá ổn
  Cũng có thể vấn đề là những người trước đây chỉ viết kiểu Fix Bugz 🚀️ giờ lại dùng LLM để soạn commit message vì muốn làm theo “best practice”
  Giả thuyết của tôi là đa số mọi người không viết commit message vì họ không đọc chúng, và họ không đọc vì năng lượng kích hoạt để tra cứu quá cao khi phải dựa vào những nơi như giao diện web của GitHub để duyệt commit

  • Câu “chi tiết không cần thiết thì khi cần có thể hỏi” là trong ngữ cảnh review
    Nếu thông tin đó quan trọng, có thể để lại thành chú thích hoặc thêm vào commit message
    KDE đã dùng Gitlab từ vài năm nay

• Về lâu dài, để việc git archaeology cho hậu thế thành công, cần có sự cân bằng
  Vì biến động nhân sự hoặc do bối cảnh phai mờ khỏi trí nhớ, thường sẽ có lúc về sau bạn không thể hỏi lại những chi tiết tưởng như không cần thiết đó
  Thời điểm tốt nhất để ghi lại bối cảnh đó là khi bạn vẫn còn nắm nó
  Có lẽ điều ta thực sự muốn là đặt các chi tiết quan trọng lên trước, và phân tách rõ ràng như một phần tổng quan

• PR hay phần giải thích mã không phải để nói về đã làm gì, mà là về tại sao lại làm vậy
  Nó nên cho biết vì sao mã có hình dạng như hiện tại và lý do đằng sau
  Điều đó tốt cho review, và cũng tốt cho việc lần lại trong lịch sử git sau này để tìm hiểu vì sao mã lại thành ra như vậy

• Giữ cho phần giải thích mã đơn giản là điều quan trọng
  Vì thứ bạn không thể hiểu hoặc không thể tập trung vào thì bạn cũng không thể đọc được
  Đồng thời, khi phát triển phần mềm, rất nhiều bối cảnh bị mai một, và hiện tại bối cảnh đó thường chỉ nằm trong đầu tác giả, người từng trao đổi với tác giả, hoặc người đã xem rất kỹ đoạn mã
  Nhưng theo tôi, bối cảnh đó nên được gắn chặt hơn nữa với mã, chứ không phải ít hơn
  Bạn không phải lúc nào cũng có thể nói chuyện với tác giả, nên cần ghi nó ở nơi luôn truy cập được và được cập nhật cùng với mã
  Trong phần lớn quy trình phát triển hiện nay, nơi phù hợp nhất cho điều đó là commit message của git
  Việc viết phần tóm tắt ở trên cùng là tốt, nhưng tôi cũng khuyến khích để lại thêm lời giải thích cho thay đổi trong mã
  Nếu đưa bối cảnh ra ngoài, kể cả những điều hiện tại có vẻ chưa quan trọng, thì bản thân tôi trong tương lai sẽ biết ơn vì điều đó
  Về sau cần có cách tiếp cận tốt hơn là chỉ nhét loại bối cảnh này vào commit message, và vì thế cá nhân tôi thích lập trình văn chương vì nó cho nhiều không gian hơn để giải thích cả “cái gì” lẫn “tại sao” của mã