Hãy tưởng tượng: bạn mở pull request vào sáng thứ Hai, tự hào về đoạn code sạch nhất mình viết trong nhiều tháng. Chiều đến, một comment duy nhất khiến bạn sợ cả tuần. Không phải vì phản hồi sai — mà vì cách nó được truyền đạt. "Cái này phức tạp không cần thiết. Sao lại làm vậy?" Bảy chữ. Không một gợi ý hành động nào. Và cả tuần bỗng trở nên nhạt thếch.
Review code là nghi thức có đòn bẩy cao nhất trong bất kỳ nhóm kỹ thuật nào. Làm tốt, nó ship phần mềm tốt hơn, giúp kỹ sư phát triển nhanh hơn, và âm thầm củng cố văn hoá tin tưởng. Làm kém, nó đốt cháy năng lượng, làm chậm việc giao hàng, và đẩy những kỹ sư giỏi nhất sang các nhóm nơi họ không phải tự vệ trong từng pull request. Hướng dẫn này là về việc làm đúng — cách diễn đạt cụ thể, checklist của reviewer, những thói quen âm thầm biến review thành độc tố, và cần làm gì khi chính bạn là người nhận comment.
Review code là văn hoá, không chỉ là bắt lỗi
Có một hiểu lầm phổ biến về mục đích của review code. Mục tiêu kỹ thuật — tìm lỗi trước khi đến môi trường production — là thật và có giá trị. Nhưng đó chỉ là một phần câu chuyện.
Mỗi comment bạn để lại đều dạy điều gì đó. Nó dạy tác giả về codebase, về sự đánh đổi, về những tiêu chuẩn nhóm quan tâm. Qua hàng trăm lần review, bạn là bộ nhớ tập thể của nhóm, được viết ra rõ ràng. Kỹ sư mới học "tốt" có nghĩa là gì ở đây thông qua việc đọc comment của bạn. Kỹ sư junior trở thành senior bằng cách nội hoá những câu hỏi reviewer thường đặt ra. Senior duy trì sự sắc bén bằng cách diễn đạt rõ lý do đằng sau bản năng của họ.
Review cũng đặt ra chuẩn mực vô hình. Một nhóm thường xuyên để lại những comment nhã nhặn, cụ thể, tò mò sẽ trở thành nơi an toàn về mặt tâm lý để ship thứ chưa hoàn hảo và học từ đó. Một nhóm để lại những comment cộc lốc, coi thường, hay bí hiểm sẽ trở thành nơi người ta over-engineer trong im lặng để tránh bị chỉ trích, trì hoãn mở PR, hay ngừng đặt câu hỏi.
Khi kỹ sư sợ mở pull request, họ gom công việc thành những changeset ngày càng lớn để giảm số lần review. PR lớn hơn thì khó review hơn, chất lượng review giảm, phản hồi trở nên khắc nghiệt hơn, và vòng xoáy ngày càng sâu. Thuốc giải không phải là ít nghiêm khắc hơn — mà là nhiều tử tế hơn song song với sự nghiêm khắc.
Không ai nói rằng review code nên là mềm mỏng hay thiếu sức mạnh. Những reviewer hiệu quả nhất thật sự thành thật. Họ chỉ ra vấn đề rõ ràng. Họ giữ vững lập trường về những điều thật sự quan trọng. Nhưng họ làm điều đó theo cách khiến tác giả cảm thấy có thêm một người cộng tác, chứ không phải đứng trước một quan toà.
Review cái gì — và bỏ qua cái gì
Một trong những lỗi review phổ biến nhất là review mọi thứ với trọng lượng như nhau. Reviewer block PR vì thiếu dấu phẩy cuối dòng có cùng quyền phủ quyết với người phát hiện SQL injection. Sự bất cân xứng đó phá vỡ niềm tin rất nhanh. Trước tiên hãy rõ ràng trong đầu về điều gì thật sự quan trọng:
- Tính đúng đắn: Code này có làm đúng những gì nó cần làm không? Các edge case có được xử lý không? Code có thể thất bại trong production theo cách test không bao phủ không?
- Thiết kế: Thay đổi này có khớp tự nhiên với kiến trúc hiện tại không? Nó có tạo ra coupling không cần thiết không? Có cách tiếp cận đơn giản hơn giải quyết cùng vấn đề không?
- Khả năng đọc: Một đồng đội không viết code này có hiểu nó sau sáu tháng không? Tên biến có rõ ràng không? Luồng xử lý có dễ theo dõi không?
- Test: Các test có có ý nghĩa không? Chúng có bao phủ happy path, edge case, và failure mode không? Một test thất bại có thực sự cho bạn biết điều gì đó hữu ích không?
- Bảo mật: Input của người dùng có được validate không? Code này có thể tạo ra rò rỉ dữ liệu, leo thang đặc quyền, hay injection không? (Nếu có, coi là blocker.)
Những gì không nên dành năng lượng review:
- Định dạng và style mà linter hoặc formatter của bạn xử lý tự động. Nếu CI của bạn bắt được, bạn không cần. Slot review của người là quý giá — đừng dùng nó cho thứ máy móc đã xử lý.
- Sở thích cá nhân không phải tiêu chuẩn nhóm. "Tôi sẽ đặt tên khác" không phải là một review comment. "Tên này không khớp với ngôn ngữ thông dụng trong phần còn lại của domain" thỉnh thoảng mới là.
- Tranh luận về kiến trúc trong thread comment của PR. Nếu bạn có bất đồng cơ bản về hướng đi, đó là cuộc trò chuyện thiết kế, không phải review code. Hãy thực hiện riêng và cộng tác trước khi PR tiếp theo bắt đầu.
Trước khi viết một comment, hãy hỏi: "Nếu tác giả thực hiện thay đổi này, code có tốt hơn một cách có ý nghĩa không?" Nếu câu trả lời là "một chút" hay "có thể", hãy cân nhắc xem có đáng thời gian của họ và bạn không. Nếu câu trả lời là "có, và đây là lý do", hãy viết nó — nhưng viết thật nhã nhặn.
Cách diễn đạt comment nhã nhặn — mà vẫn thành thật
Đòn bẩy lớn nhất trong review code là lựa chọn từ ngữ. Cùng một mối lo ngại, được trình bày theo hai cách khác nhau, tạo ra phản ứng hoàn toàn khác nhau ở người đọc. Đây là bộ công cụ thực tế:
- Đặt câu hỏi thay vì đưa ra phán xét. "Tại sao bạn chọn X thay vì Y ở đây?" mở ra một cuộc trò chuyện. "Bạn nên dùng Y" đóng nó lại. Câu hỏi có thể tiết lộ ngữ cảnh bạn chưa có — và dù không, tác giả vẫn đi đến cùng kết luận mà không cảm thấy bị buộc tội.
- Giải thích lý do, không chỉ nói cái gì. "Chúng ta có thể chuyển logic này vào một service không?" yếu hơn "Chúng ta có thể chuyển logic này vào một service không? Giữ nó trong controller khiến test độc lập khó hơn, và ta sẽ phải duplicate nếu một cron job cũng cần behaviour tương tự." Lý do dạy; chỉ việc phải làm chỉ là ra lệnh.
- Đề xuất giải pháp, không chỉ chỉ trích. Nếu bạn thấy vấn đề, hãy chỉ ra bạn sẽ làm gì thay thế — hay ít nhất là hình dạng của nó. "Tôi không chắc về cái này, nhưng đại loại như…" hữu ích hơn nhiều so với "cái này có vẻ không ổn."
- Khen ngợi code tốt một cách rõ ràng. "Cách xử lý lỗi này thật sự sạch — tôi sẽ học theo pattern này" mất mười giây và không tốn gì. Nó củng cố sự tự tin của tác giả, nó tăng cường pattern như một chuẩn mực nhóm, và nó giúp những comment phê bình sau đó được tiếp nhận tốt hơn.
- Dùng "chúng ta" và "của chúng ta" khi thành thật. "Quy ước của chúng ta là giữ cái này gần repository" nhẹ nhàng hơn "bạn đặt nhầm chỗ" mà không kém chính xác hơn.
Khắc nghiệt vs nhã nhặn: cùng một ý, hai cách diễn đạt
| Khắc nghiệt (nhưng kỹ thuật đúng) | Nhã nhặn — và vẫn thành thật |
|---|---|
| "Cái này sai. Bạn cần xử lý trường hợp null." | "Cái này sẽ throw nếu user là null — chúng ta có thể thêm guard ở đây hoặc document rằng caller đảm bảo nó không null không?" |
| "Sao lại làm vậy? Cái này phức tạp không cần thiết." | "Tôi thấy khó theo dõi đoạn này — có cách đơn giản hơn để diễn đạt không? Có thể tôi đang thiếu ngữ cảnh, chat nếu cần nhé." |
| "Function này làm quá nhiều thứ. Tách ra." | "Function này đang xử lý cả validation lẫn persistence — tách hai trách nhiệm đó ra có thể giúp mỗi phần dễ test độc lập hơn. Bạn thấy sao?" |
| "Bạn rõ ràng chưa test cái này." | "Tôi không thấy test cho trường hợp input rỗng — đó là chủ ý, hay mình mở ticket theo dõi không?" |
"Dùng const đây, không phải let." |
"nit: const ở đây vì nó không bao giờ được gán lại — làm rõ ý định hơn." |
| "Đây là lỗ hổng bảo mật." | "blocking: input này do người dùng cung cấp và đi thẳng vào query — đó là rủi ro injection. Chúng ta có thể parameterise trước khi merge không?" |
| "Abstraction sai." | "Tôi tự hỏi liệu abstraction này có đang kéo đúng hướng không — có vẻ có thể làm tính năng tiếp theo khó hơn. Sync nhanh được không?" |
Hãy chú ý cột "nhã nhặn" không phải là: mềm mỏng, mơ hồ, hay không thành thật. Vấn đề bảo mật vẫn được gắn blocker. Trường hợp null vẫn cần sửa. Function vẫn cần tách. Nhã nhặn ở đây có nghĩa là: cụ thể, có giải thích, và được truyền đạt như một người nói chuyện với người khác, không phải quan toà tuyên án.
Nitpick, đề xuất, và blocker — hãy gắn nhãn
Một trong những việc thực tế nhất bạn có thể làm cho văn hoá review là gắn nhãn mức độ nghiêm trọng của mỗi comment. Không có nhãn, tác giả phải đoán xem mỗi comment có nghĩa là "merge bị block" hay "chỉ là suy nghĩ". Việc đoán đó tốn năng lượng và thường cho ra kết quả sai.
Quy ước đơn giản được nhiều nhóm dùng (phổ biến hóa bởi Conventional Comments):
- nit: điểm nhỏ về style hay sở thích — sửa hay không là tác giả quyết định. "nit: dấu phẩy cuối dòng này khớp với phần còn lại của file."
- suggestion: thứ gì đó sẽ cải thiện code nhưng không phải blocker. "suggestion: có thể extract cái này thành helper — không bắt buộc cho PR này."
- blocking: PR không nên merge cho đến khi điều này được giải quyết. Dành cho lỗi tính đúng đắn, vấn đề bảo mật, và vi phạm rõ ràng tiêu chuẩn nhóm.
- question: bạn hỏi thật lòng, không ám chỉ cần thay đổi gì. "question: cái này có chạy trên background worker cũng không, hay chỉ web process?"
- praise: phản hồi tích cực rõ ràng, chân thành. Có giá trị. Đừng bỏ qua.
Khi tất cả blocking issue được giải quyết, hãy approve với comment còn lại. Đây là thói quen quan trọng. Nó có nghĩa: "Tôi tin bạn xử lý được các nit còn lại; bạn không cần thêm một vòng từ tôi." Nó unblock đồng nghiệp, nó báo hiệu sự tin tưởng, và giữ vòng review không trở thành nút cổ chai. Cách ngược lại — giữ approval cho đến khi mọi điểm nhỏ được xử lý — là một trong những độc tố âm thầm trong văn hoá review.
Khi tất cả blocking item được giải quyết, hãy approve và để tác giả quyết định phần còn lại. Giữ PR con tin vì nit dạy người ta rằng review là chướng ngại vật, không phải sự cộng tác. Nếu bạn thật sự quan tâm đến một điểm không blocking, hãy nói rõ — "tôi quan tâm đến điều này, nhưng là quyết định của bạn" — để tác giả có đầy đủ thông tin.
Phía tác giả: nhận phản hồi mà không bị cá nhân hoá
Được review là một kỹ năng riêng, và hầu hết bài viết về văn hoá kỹ thuật chỉ tập trung vào reviewer. Nhưng hành vi của tác giả định hình văn hoá review không kém.
Giả định thiện chí mặc định. Một comment cộc lốc hầu như luôn là người bận rộn viết vội, không phải ai đó cố làm bạn tổn thương. Trước khi bạn đọc giọng điệu vào một comment, hãy hỏi liệu có cách diễn giải trung lập hay tích cực không. Thường là có.
Trả lời mọi comment. Dù bạn không đồng ý. Một ✅ hay "done" trên phản hồi đã thực hiện, và một giải thích cho bất cứ điều gì bạn phản đối, đóng vòng lặp và cho reviewer thấy thời gian của họ được trân trọng. Im lặng bị đọc là thái độ bị động dù bạn có cố ý hay không.
Phản đối khi bạn thật sự không đồng ý — rõ ràng và bình tĩnh. "Tôi thấy vấn đề, nhưng đây là lý do tôi đưa ra lựa chọn này: [lý do]. Sẵn sàng thảo luận nếu bạn vẫn thấy quan trọng." Điều này không giống với việc tự vệ phản xạ cho mọi quyết định. Mục tiêu là có một cuộc trò chuyện thật, không phải để thắng. Đôi khi reviewer đúng. Đôi khi bạn đúng. Đôi khi câu trả lời đúng là "hãy đưa điều này cho cả nhóm."
Đừng giải thích quá dài về code của bạn trong PR description. Nếu code cần một bức tường chữ để biện minh cho mọi quyết định, đó là tín hiệu để cải thiện code, tên biến, hay comment inline — không phải viết PR description dài hơn. Những PR tốt nhất tự giải thích được với mô tả ngữ cảnh và ý định tốt.
Tốc độ review và kích thước PR — hai đòn bẩy có tác động lớn
Chất lượng của một review code được dự đoán mạnh mẽ bởi hai thứ không liên quan đến kỹ năng của reviewer: tốc độ họ review và kích thước của PR.
Review kịp thời. Một pull request chờ review là một người chờ tiếp tục. Khi review mất nhiều ngày, công việc bị dồn lại — kỹ sư mở task tiếp theo để duy trì năng suất, context switch tăng lên, và khi review trả lại thì tác giả đã quên mình đang nghĩ gì. Nguyên tắc tốt: acknowledge PR trong vài giờ sau khi được tag (dù chỉ "tôi sẽ xem trước cuối ngày"), và hoàn thành review trong một ngày làm việc khi có thể.
PR nhỏ hơn nhận được review tốt hơn đáng kể. Điều này đã được ghi nhận rõ ràng và cũng rõ ràng trong thực tế. Một PR 100 dòng nhận được sự chú ý kỹ lưỡng từng dòng. Một PR 1.000 dòng bị rubber-stamp, lướt qua, hoặc review quá chậm đến mức trở thành nguồn xung đột. Kỷ luật giữ PR nhỏ — "một thay đổi logic mỗi PR" là heuristic tốt — mang lại lợi ích hơn hầu hết mọi cải tiến vệ sinh review khác. Nó cũng làm mỗi PR dễ viết hơn, vì bạn phải suy nghĩ rõ ràng về ý nghĩa của một thay đổi.
| Kích thước PR (dòng thay đổi) | Chất lượng review thông thường | Thời gian review |
|---|---|---|
| < 200 dòng | Cao — reviewer có thể giữ trong bộ nhớ làm việc | 15–45 phút |
| 200–500 dòng | Trung bình — mệt mỏi xuất hiện với các vấn đề tinh tế | 45–90 phút |
| 500–1.000 dòng | Giảm — reviewer lướt qua hoặc chia thành nhiều phiên | Vài giờ đến một ngày |
| > 1.000 dòng | Hầu như chỉ hình thức — vấn đề quan trọng thường xuyên bị bỏ qua | Vài ngày (hoặc không bao giờ đủ) |
Nếu một tính năng thực sự cần hàng nghìn dòng, hãy cân nhắc stacked PR: một loạt thay đổi nhỏ, độc lập, xây trên nhau, mỗi cái có thể review theo giá trị riêng của nó. Chi phí mở thêm PR hầu như luôn đáng giá.
Văn hoá review khác nhau theo quy mô nhóm
Cách tiếp cận đúng với review code thay đổi đáng kể khi nhóm phát triển. Những gì hiệu quả với ba kỹ sư thường bắt đầu thất bại ở ba mươi, và nhóm cỡ enterprise cần công cụ hoàn toàn khác.
Solo hoặc startup sơ khai (1–5 kỹ sư). Ở quy mô này có thể không có review nào cả, đôi khi ổn và đôi khi thảm hoạ tuỳ mức độ quan trọng. Khi có review, mối quan hệ thường đủ mạnh để phản hồi thẳng thắn tiếp nhận tốt — nhưng đây cũng là giai đoạn thói quen xấu được cố định trước khi ai đó nghĩ đến việc đặt tên cho chúng. Hãy hình thành thói quen gắn nhãn mức độ nghiêm trọng của comment sớm; chi phí bằng không và trở nên vô giá sau này.
Nhóm nhỏ đang lớn (5–20 kỹ sư). Đây là lúc văn hoá review được định hình. Nhóm đủ lớn để cái shorthand "chúng ta đều quen nhau" bắt đầu mờ đi, nhưng đủ nhỏ để các chuẩn mực vẫn có thể được thiết lập bởi vài giọng nói có ảnh hưởng. Một senior engineer duy nhất làm mẫu review nhã nhặn, cụ thể, có gắn nhãn sẽ thay đổi văn hoá của cả nhóm trong vài tháng. Đây cũng là lúc một hướng dẫn review của nhóm — dù chỉ một trang — mang lại lợi tức: điều gì là blocker, điều gì là nit, review nên mất bao lâu.
Nhóm cỡ trung (20–100 kỹ sư). Review lúc này xảy ra giữa các squad gần như không biết nhau. Công việc xây dựng tin tưởng xảy ra tự nhiên trong nhóm nhỏ giờ phải được thực hiện có chủ đích. Review xuyên nhóm trở thành nguồn ma sát lớn nếu chuẩn mực không được chia sẻ. Code owner, luân phiên review, và checklist review nhẹ giúp ích. Việc biến chất lượng review thành chủ đề trong retrospective kỹ thuật cũng vậy — không chỉ "chúng ta ship nhanh không" mà "chúng ta review tốt không".
Nhóm lớn hoặc enterprise (100+ kỹ sư). Ở quy mô này, review là chức năng quản trị và tuân thủ không kém chức năng chất lượng. Tooling quan trọng rất nhiều: automated check, required reviewer, review SLA, và metric về review cycle time. Slot review của người quý giá và nên được dành cho những gì chỉ người mới làm được — phán đoán thiết kế, kiến thức domain, tác động xuyên nhóm. Bất cứ thứ gì linter hay static analyser có thể bắt thì nên bị bắt trước khi PR được mở, không phải trong thread comment.
Những điều cốt lõi cần nhớ
- Review code là văn hoá trước, bắt lỗi sau. Mỗi comment dạy điều gì đó, và các pattern comment xây dựng hoặc phá hoại an toàn tâm lý theo từng tháng.
- Tập trung năng lượng review vào điều quan trọng: tính đúng đắn, thiết kế, khả năng đọc, test, và bảo mật. Để linter xử lý định dạng.
- Nhã nhặn + Cụ thể là mục tiêu. Giải thích lý do, đặt câu hỏi thay vì đưa ra phán xét, và khen ngợi code tốt một cách rõ ràng.
- Gắn nhãn comment của bạn: nit / suggestion / blocking / question / praise. Nó loại bỏ sự mơ hồ và tôn trọng thời gian của tác giả.
- Approve với comment khi tất cả blocker được giải quyết. Đừng giữ PR con tin vì nitpick.
- Với tư cách tác giả: giả định thiện chí, trả lời mọi comment, phản đối bình tĩnh khi không đồng ý, và đừng giải thích quá dài trong PR description.
- PR nhỏ hơn, review nhanh hơn. Dưới 200 dòng nhận được sự chú ý tốt nhất. Stacked PR xử lý các tính năng lớn.
- Chuẩn mực review cần có chủ đích — đặc biệt khi nhóm vượt qua 10–20 người. Viết chúng ra, xem lại trong retro.
Nếu bài này có ích, bài tiếp theo trong loạt này sẽ mở rộng hơn — từ cách bạn review code đến cách bạn xuất hiện như một kỹ sư mỗi ngày: Kind Engineering.