Đến nội dung chính
notes.vinhnq.com

Tìm kiếm

Git, DevOps & ToolingSenior21 phút đọc

Code review: mục tiêu, checklist, quy trình và cách viết comment

Ôn 15 thẻ
Trong bài này

Cụm bài Code review: 1. Mục tiêu, quy trình và cách viết comment · 2. Giải quyết bất đồng và review mẫu

Review hay hỏng theo hai kiểu: hình thức (approve PR 1.500 dòng trong hai phút) hoặc thành chiến trường (ba mươi comment về đặt tên, cãi cả tuần). Bài này gom những gì cần để review có ích: mục tiêu, checklist, quy trình, kích thước PR, cách viết comment và công cụ. Bài 2 nói về cách xử lý bất đồng, kèm hai buổi review mẫu trên code thật đi kèm khoá học.

Bài liên quan: Git và commit convention cho phía tác giả; Clean code: đặt tên, hàm và luồng điều khiển cho những gì reviewer nhìn vào khi đánh giá độ dễ đọc.

1. Review để làm gì

Ý chính: để kiểm soát chất lượng và để người trong team học lẫn nhau. Review không thay test, cũng không phải chỗ áp khẩu vị cá nhân.

  1. Kiểm soát chất lượng, ở hai tầng:
    • Sản phẩm: bug, lỗ hổng bảo mật, hành vi sai so với yêu cầu.
    • Codebase: thiết kế, khả năng bảo trì, tính nhất quán. Test không đo được những thứ này, nhưng chúng quyết định tốc độ của team sau sáu tháng.
  2. Phát triển con người. Hard skill: reviewer học phần code mình chưa biết, tác giả học cách làm tốt hơn. Soft skill: tác giả tập trình bày thay đổi, reviewer tập góp ý sao cho người ta muốn nghe.

Hệ quả phụ: kiến thức lan ra. Mỗi phần code có ít nhất hai người hiểu, nên một người nghỉ không làm team đứng (tăng “bus factor” — số người team mất đi thì dự án đứng). Tìm mọi bug là việc của test và CI.

2. Review cái gì: checklist

Ý chính: khoá học liệt kê bảy mục: chức năng, thiết kế, độ dễ đọc, tính nhất quán, test, tài liệu, và khen điểm tốt. Với backend, thêm concurrency/transaction, lỗi và timeout, bảo mật, hiệu năng, tương thích dữ liệu, và khả năng quan sát.

Thứ tự đọc quan trọng không kém: mô tả PR (biết mục đích) → test (biết hành vi mong muốn) → file lớn nhất về thiết kế (interface, entity, migration) → chi tiết. Đọc theo thứ tự file GitHub sắp dễ sa vào chi tiết trước khi hiểu tổng thể.

Bảng checklist đầy đủ cho Java/Spring, kèm câu hỏi và ví dụ
Khía cạnh Câu hỏi Ví dụ backend
Chức năng Code làm đúng yêu cầu chưa? Các case biên? Đặt phòng 0 đêm, check-in đúng hôm nay, số khách bằng sức chứa
Thiết kế Đặt đúng tầng chưa? Có phức tạp hơn cần không? Logic nghiệp vụ trong controller; interface chỉ có một implementation
Dễ đọc Người khác đọc có hiểu không cần hỏi? Tên biến aDays, method 200 dòng, comment nói “cái gì” thay vì “vì sao”
Nhất quán Có theo convention của repo? Response envelope, mã lỗi, cách đặt tên endpoint
Test Test có kiểm tra hành vi, có case lỗi không? Chỉ có happy path; mock cả thứ đang được test
Tài liệu README, API doc, ADR có cần cập nhật? Endpoint mới chưa có trong OpenAPI
Concurrency, transaction Hai request cùng lúc thì sao? Transaction bao đến đâu? SELECT ... FOR UPDATE thiếu ORDER BY; gọi HTTP bên trong transaction
Lỗi và timeout Phụ thuộc ngoài chậm hoặc chết thì sao? Không đặt timeout; retry không idempotent
Bảo mật Input có được kiểm tra? Có lộ dữ liệu? Nối chuỗi vào SQL; log số thẻ; thiếu kiểm tra quyền sở hữu
Hiệu năng Có N+1, query không index, load cả bảng? findAll() rồi lọc trong Java
Dữ liệu và tương thích Migration có chạy được trên bảng lớn? API cũ còn dùng được? Thêm cột NOT NULL không default; đổi tên field JSON
Quan sát được Lỗi xảy ra thì có log, metric đủ để điều tra? catch (Exception e) {}; log thiếu request id
Điểm tốt Có gì đáng học? Một test tái hiện race condition; một tên hàm rất rõ

3. Quy trình

Ý chính: thay đổi nhỏ → peer review bất đồng bộ trên MR; thay đổi lớn → group review trong một buổi. Tác giả chịu phần lớn trách nhiệm: tự review, viết mô tả, chỉ gán reviewer khi CI xanh. Code do AI agent viết cũng vậy: tác giả tự kiểm chứng trước khi nhờ review (làm việc với AI coding agent).

Peer review cần một (hoặc hai) reviewer. Group review: tác giả trình bày thiết kế và điểm rủi ro cho nhóm liên quan. Với thay đổi kiến trúc, nên duyệt design doc trước khi viết code, để buổi review code không thành buổi cãi thiết kế.

Luồng của khoá học, mình diễn đạt lại:

flowchart TD
  A[Tác giả làm xong feature/bugfix] --> B[Tự review diff, viết mô tả MR có bối cảnh]
  B --> C{Build và test trên CI xanh?}
  C -- không --> A
  C -- có --> D{Thay đổi lớn?}
  D -- không --> E[Gán reviewer: peer review]
  D -- có --> F[Hẹn buổi group review]
  E --> G[Reviewer đọc theo checklist, comment có nhãn]
  F --> G
  G --> H{Có comment chặn?}
  H -- có --> I[Tác giả sửa các điểm đã thống nhất, trả lời từng comment]
  I --> G
  H -- không --> J[Reviewer approve, merge]

Phía tác giả:

  • Tự đọc lại diff trước. Phần lớn lỗi vặt (log debug quên xoá, file thừa) bị bắt ở đây.
  • Viết mô tả: vì sao, thay đổi gì, test thế nào, rủi ro và cách rollback (template bên dưới).
  • Chỉ gán reviewer khi CI xanh: reviewer không nên đọc code chưa biên dịch.
## Vì sao
Booking bị tạo trùng khi client retry (ticket BOOK-142).

## Thay đổi
- Thêm UNIQUE(request_id) cho bảng booking (migration V42, tạo index CONCURRENTLY).
- Service trả về booking cũ khi gặp request_id đã tồn tại.

## Kiểm tra
- Test tích hợp: hai request cùng request_id song song -> 1 booking, 2 response giống nhau.
- Chạy migration trên bản sao dữ liệu staging: 38 giây, không khoá bảng.

## Rủi ro và rollback
- Dữ liệu cũ có 12 request_id trùng: đã gộp ở V41. Rollback: drop index, code cũ vẫn chạy.

Phía reviewer: đọc theo checklist, trả lời nhanh. Google đặt tối đa một ngày làm việc cho lần phản hồi đầu; nhiều team đặt vài giờ. Review chậm làm tác giả chuyển việc rồi phải nạp lại bối cảnh, và khuyến khích PR to (“đằng nào cũng chờ lâu”).

4. Kích thước thay đổi

Ý chính: thay đổi nhỏ thì review nhanh, kỹ và ra code tốt hơn. Slide ghi “Google khoảng 250 dòng, giữ dưới 400 dòng”: ý đúng, nhưng con số trích sai nguồn.

Cách chia một thay đổi lớn:

  • Tách refactor khỏi thay đổi hành vi. PR 1 đổi tên, dời file, tách method (test cũ vẫn xanh); PR 2 mới thêm logic. PR 1 review rất nhanh vì chỉ cần kiểm “không đổi hành vi”.
  • Xếp chồng PR (stacked PRs): PR 2 dựa trên nhánh của PR 1, mỗi PR review riêng.
  • Feature flag: merge từng phần chưa bật, bật khi đủ.
  • Migration riêng, kiểu expand/contract: thêm cột mới (expand), deploy code ghi cả hai, backfill, chuyển đọc sang cột mới, rồi mới xoá cột cũ (contract). Mỗi bước một PR.
  • Thay đổi sinh tự động (format toàn repo, code generate, nâng version thư viện) ở PR riêng, ghi rõ trong mô tả.

5. Thái độ và cách viết comment

Ý chính: ba nguyên tắc của khoá học: lịch sự, đóng góp (đưa cách tốt hơn, không chỉ chỉ ra cái sai), dạy chứ không chê. Và gắn nhãn mọi comment để tác giả biết cái nào chặn merge.

  • Comment về code, không về người: “hàm này nhận null thì sao?” thay vì “bạn không nghĩ tới null à?”.
  • Giải thích vì sao, kèm link nếu có (tài liệu, bài viết, một bug cũ).
  • Đưa phương án, tốt nhất là đoạn code gợi ý (tính năng “suggestion” của GitHub/GitLab cho tác giả bấm áp dụng).
  • Hỏi khi không chắc: “mình hiểu là X, đúng không?” hay mở ra thông tin reviewer không có.
  • Khen cụ thể: không phải xã giao, nó cho tác giả biết cái gì nên giữ.
Nhãn Nghĩa Chặn merge?
TODO Lỗi thật hoặc rủi ro, phải sửa Có
NIT Chi tiết nhỏ (đặt tên, format) Không
OPTIONAL Gợi ý, tác giả tự quyết Không
FYI Thông tin để biết, không cần làm gì Không

Mình thêm hai nhãn: QUESTION (cần câu trả lời, chưa phải yêu cầu sửa) và PRAISE (điểm tốt).

Ví dụ comment kém và tốt hơn, và Conventional Comments
Comment kém Comment tốt hơn
“Sai rồi.” “TODO: field này không final nên @RequiredArgsConstructor không đưa vào constructor, Spring không inject, request đầu tiên sẽ NPE. Đề nghị thêm final.”
“Sao không dùng Optional?” “OPTIONAL: trả Optional<Booking> sẽ buộc chỗ gọi xử lý trường hợp không có, thay vì quên kiểm tra null. Không bắt buộc trong PR này.”
“Tên tệ quá.” “NIT: aDays hơi khó đoán, availableNights có rõ hơn không?”
(không nói gì về điểm tốt) “PRAISE: test tái hiện hai booking song song rất hay, mình sẽ dùng lại cách này.”

6. Công cụ: để máy nói những gì máy nói được

Ý chính: cái gì máy kiểm tra được thì để CI kiểm tra, để người review tập trung vào thiết kế và hành vi. Chặn merge bằng check nhanh và chắc; cảnh báo với check cần phán đoán.

Loại (repo Spring Boot) Công cụ
Format Spotless với google-java-format hay palantir-java-format, chạy trên CI. Không ai phải comment về dấu cách nữa.
Lint, phân tích tĩnh Checkstyle (convention), Error Prone (so sánh sai kiểu, bỏ qua giá trị trả về), SpotBugs và PMD (null, tài nguyên không đóng, đồng bộ sai), SonarQube tổng hợp và quality gate
Kiến trúc ArchUnit: luật phụ thuộc viết thành test
Dependency, bí mật Dependabot hoặc Renovate nâng version; OWASP Dependency-Check hay tính năng quét của nền tảng bắt CVE; gitleaks chặn secret bị commit
Test, coverage JaCoCo; coverage trên phần code thay đổi (diff coverage) hữu ích hơn một con số cho cả repo
Nền tảng CODEOWNERS tự gán reviewer theo thư mục; branch protection (cấm push thẳng, bắt CI xanh, bắt N approve); template mô tả PR

Ví dụ ArchUnit: controller không gọi repository, và luật bắt đúng lỗi trong buổi review mẫu ở bài 2 (cần dependency archunit-junit5, không chạy trong bài):

@AnalyzeClasses(packages = "com.example.booking")
class ArchitectureTest {
    @ArchTest
    static final ArchRule servicesUseFinalFields = fields()
            .that().areDeclaredInClassesThat().areAnnotatedWith(Service.class)
            .and().areNotStatic()
            .should().beFinal()
            .because("@RequiredArgsConstructor only injects final fields");

    @ArchTest
    static final ArchRule controllersDoNotTouchRepositories = noClasses()
            .that().areAnnotatedWith(RestController.class)
            .should().dependOnClassesThat().areAssignableTo(Repository.class);
}

Khi team đã chọn kiến trúc (layered, hexagonal, clean), viết luật phụ thuộc của nó thành test ArchUnit thay vì trông vào mắt người review; luật mẫu cho từng kiểu có ở Kiến trúc codebase.

Bài tập

Bài 1: Viết comment có nhãn cho một đoạn code

Đề: review đoạn code dưới đây như trên một MR thật: tìm vấn đề, gắn nhãn, viết comment có hậu quả và cách sửa.

@RestController
@RequiredArgsConstructor
public class OrderController {
    private final JdbcTemplate jdbc;
    private final OrderItemRepository items;
    private static final SimpleDateFormat FMT = new SimpleDateFormat("yyyy-MM-dd");

    @GetMapping("/orders")
    public List<OrderDto> search(@RequestParam String status, @RequestParam String from) {
        try {
            String sql = "SELECT * FROM orders WHERE status = '" + status + "' AND created_at >= '" + from + "'";
            List<Order> orders = jdbc.query(sql, new BeanPropertyRowMapper<>(Order.class));
            List<OrderDto> result = new ArrayList<>();
            for (Order o : orders) {
                result.add(new OrderDto(o.getId(), FMT.format(o.getCreatedAt()), items.findByOrderId(o.getId())));
            }
            return result;
        } catch (Exception e) {
            return List.of();
        }
    }
}
Lời giải Bài 1: bảy comment có nhãn
  1. TODO: nối chuỗi status và from vào SQL là SQL injection (status=' OR '1'='1). Dùng tham số ? của JdbcTemplate (hoặc NamedParameterJdbcTemplate), và parse from thành LocalDate ở tầng controller để input sai bị từ chối với 400.
  2. TODO: catch (Exception e) { return List.of(); } biến mọi lỗi (DB chết, bug) thành “không có đơn nào”, người dùng và on-call đều không biết có lỗi. Bỏ catch, để handler toàn cục trả 500 và log (xem Xử lý lỗi trong Spring Boot).
  3. TODO: SimpleDateFormat không thread-safe, mà ở đây là field static dùng chung cho mọi request: dưới tải sẽ ra ngày sai hoặc exception. Dùng DateTimeFormatter (immutable, thread-safe) với java.time.
  4. TODO: gọi items.findByOrderId trong vòng lặp là N+1 query: 500 đơn là 501 query. Lấy items của mọi đơn trong một query (WHERE order_id IN (...)) rồi gom bằng Map.
  5. TODO: không phân trang và SELECT *: một status phổ biến có thể trả cả trăm nghìn dòng. Thêm limit có giới hạn tối đa, chọn đúng cột.
  6. NIT: logic truy vấn nằm trong controller; chuyển sang service/repository để test được riêng.
  7. QUESTION: status nhận giá trị tự do; có danh sách hợp lệ không? Nếu có, dùng enum để Spring từ chối giá trị lạ.

Bài 2: Chia một PR 1.400 dòng

Đề: một PR “thêm thanh toán qua ví” gồm: đổi tên package payment thành billing (600 dòng, toàn import), migration thêm bảng wallet_transaction, client gọi API ví, service xử lý callback, endpoint mới, và format lại vài file cũ. Đề xuất cách chia.

Lời giải Bài 2: sáu PR nối tiếp
  1. PR đổi tên package: chỉ đổi tên, không đổi hành vi; reviewer kiểm bằng “CI xanh, diff chỉ có import”.
  2. PR format riêng (hoặc bật Spotless cho cả repo trong một PR riêng).
  3. PR migration bảng mới (chưa ai dùng, an toàn deploy trước).
  4. PR client gọi ví + adapter + test với server giả (WireMock).
  5. PR service callback + endpoint, sau feature flag tắt.
  6. PR bật flag cho nhóm nhỏ.

Mô tả của PR (4) trở đi trỏ về issue tổng. Mỗi PR dưới khoảng 300 dòng thay đổi có nghĩa, review được trong một buổi ngắn.

Ghi nhớ

  • Nêu được hai mục tiêu của review và một việc review không nhằm làm.
  • Biết đọc PR theo thứ tự nào, và vì sao chỉ đọc diff là chưa đủ.
  • Trích đúng nguồn con số kích thước PR: Google (100 / 1.000 dòng) và SmartBear tại Cisco (~400 dòng, 60–90 phút).
  • Viết được một comment có nhãn, nói hậu quả và cách sửa; biết nhãn nào chặn merge.
  • Biết đưa những check nào vào CI để chặn, cái nào chỉ cảnh báo.

Câu hỏi phỏng vấn

Junior

Code review nhằm mục đích gì?

Kiểm soát chất lượng và phát triển con người.

Chất lượng gồm bug, bảo mật, thiết kế và khả năng bảo trì của codebase. Con người: reviewer và tác giả học lẫn nhau, tập trình bày và lắng nghe. Kèm theo là kiến thức lan ra trong team. Review không thay test và không phải chỗ áp khẩu vị cá nhân.

Bạn chuẩn bị gì trước khi gửi một PR để review?

Tự review diff, đảm bảo CI xanh, và viết mô tả đủ bối cảnh.

Xoá code debug, chạy test. Mô tả gồm vì sao, thay đổi gì, test thế nào, rủi ro và cách rollback. Giữ PR nhỏ và tập trung một việc; tách refactor và format sang PR riêng.

Các nhãn TODO, NIT, OPTIONAL, FYI trong comment review nghĩa là gì?

TODO phải sửa trước khi merge; NIT là chi tiết nhỏ không chặn; OPTIONAL là gợi ý tác giả tự quyết; FYI là thông tin để biết.

Gắn nhãn giúp tác giả biết comment nào là điều kiện merge, và giúp reviewer không vô tình chặn PR vì khẩu vị.

Mid

Khi review một PR backend, bạn nhìn vào những gì ngoài việc code chạy đúng?

Những thứ test happy path không bắt: concurrency, lỗi phụ thuộc ngoài, bảo mật, hiệu năng, tương thích và khả năng quan sát.

  • Concurrency và phạm vi transaction (hai request cùng lúc, side effect trong transaction).
  • Lỗi và timeout của phụ thuộc ngoài.
  • Bảo mật: input, phân quyền, log dữ liệu nhạy cảm.
  • Hiệu năng: N+1, thiếu index, không phân trang.
  • Tương thích: migration trên bảng lớn, đổi API.
  • Log, metric; và test có kiểm tra case lỗi không.
PR bao nhiêu dòng là vừa? Vì sao?

Càng nhỏ càng tốt: Google coi ~100 dòng là hợp lý và 1.000 dòng thường quá lớn.

Nghiên cứu của SmartBear tại Cisco thấy khả năng phát hiện lỗi giảm khi một lần review vượt ~400 dòng hoặc 60–90 phút. Con số chính xác không quan trọng bằng nguyên tắc: PR nhỏ được review kỹ và nhanh, PR lớn bị lướt.

Một reviewer để 30 comment về đặt tên và format. Bạn xử lý thế nào ở mức team?

Chuyển phần máy kiểm tra được sang CI, và thống nhất nhãn để góp ý khẩu vị là NIT không chặn.

Formatter, Checkstyle, quy ước đặt tên trong hướng dẫn đóng góp, chạy trên CI. Nói riêng với reviewer về việc tập trung vào thiết kế và hành vi. Comment về format trên PR nên gần như biến mất.

Senior

Làm sao để review không thành nút cổ chai của team?

PR nhỏ, mục tiêu thời gian phản hồi được đo, và tự động hoá phần máy làm được.

  • Mục tiêu phản hồi vài giờ, tối đa một ngày làm việc, và theo dõi nó.
  • CODEOWNERS để tự gán và chia tải; cho phép approve kèm NIT.
  • Pair với người mới thay vì review nhiều vòng.
  • Thay đổi rủi ro thấp có thể merge rồi review.
  • Đo cycle time của PR để thấy vấn đề thay vì cảm tính.
Bạn đưa luật nào vào CI để giảm việc cho người review một codebase Spring Boot?

Formatter, lint và phân tích tĩnh, test với diff coverage, quét dependency và secret, và luật kiến trúc bằng ArchUnit.

Cụ thể: Spotless, Checkstyle, Error Prone hoặc SpotBugs. Luật ArchUnit: controller không gọi repository, field trong @Service phải final, package domain không phụ thuộc web. Chặn check nhanh và chắc; cảnh báo check cần phán đoán; sửa ngay check flaky.

Từ vựng tiếng Anh

Term Phát âm Nghĩa Ví dụ câu tiếng Anh dùng trong phỏng vấn
pull request / merge request /pʊl rɪˈkwest/ yêu cầu gộp thay đổi vào nhánh chính “I keep pull requests under a few hundred lines so they get a real review.”
reviewer / author /rɪˈvjuːə ˈɔːθə/ người review / người viết code “The author owns the description; the reviewer owns a timely response.”
blocking comment /ˈblɒkɪŋ ˈkɒment/ comment phải xử lý trước khi merge “Only correctness and security issues are blocking comments.”
nitpick /ˈnɪtpɪk/ góp ý chi tiết nhỏ “I prefix style suggestions with ‘nit’ so nobody feels obliged to change them.”
LGTM /el dʒiː tiː em/ “looks good to me”, đồng ý merge “I approved with LGTM and two optional nits.”
self-review /self rɪˈvjuː/ tác giả tự review trước “A quick self-review catches most leftover debug code.”
stacked PRs /stækt piː ɑːz/ chuỗi PR nối tiếp nhau “We shipped the migration as stacked PRs behind a feature flag.”
expand/contract /ɪkˈspænd ˈkɒntrækt/ đổi schema qua nhiều bước tương thích “Renaming the column took three deploys using expand and contract.”
static analysis /ˈstætɪk əˈnæləsɪs/ phân tích code không cần chạy “Static analysis flags the obvious issues before a human looks.”
quality gate /ˈkwɒləti ɡeɪt/ điều kiện tự động để được merge “The quality gate blocks merges when diff coverage drops.”
flaky test /ˈfleɪki test/ test lúc qua lúc trượt “We quarantine a flaky test immediately instead of rerunning it.”
bus factor /bʌs ˈfæktə/ số người mà team mất đi thì dự án đứng “Reviews raise the bus factor because every module has a second reader.”

Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.