English for IT
Trang chủ / Module 9
✍️ Module 9 / 20 · 6 ngày 📅 Tuần 7 ●●○○ Trung bình

Viết kỹ thuật: commit, PR, code review, bug report, email

Viết commit message chuẩn, PR description khiến reviewer duyệt nhanh, comment review có phân cấp (nit / suggestion / blocking) và giọng điệu xây dựng, phản hồi review, bug report tái hiện được, email cho khách hàng và quản lý.

CommitPull requestCode reviewBug reportEmail
📌 Vì sao module này quan trọng

Ở nhóm phân tán, chữ viết của bạn là "bạn" khi bạn ngủ. PR description tốt rút ngắn thời gian review từ 2 ngày xuống 2 giờ. Comment review gắt có thể làm hỏng quan hệ với đồng nghiệp; comment quá mềm thì bị bỏ qua. Viết tốt là kỹ năng tạo đòn bẩy lớn nhất cho dev làm việc với nước ngoài — và nó luyện được nhanh hơn nói rất nhiều.

🎯 Mục tiêu học tập

  • Viết commit message dạng mệnh lệnh theo Conventional Commits
  • Viết PR description: Why → What → How to test → Risks
  • Comment review có nhãn mức độ và giọng điệu xây dựng; phản hồi review chuyên nghiệp
  • Viết bug report tái hiện được 100%
  • Viết email ngắn theo nguyên tắc BLUF (Bottom Line Up Front)
🎧 Cách học trang này

Bấm 🔊 cạnh mỗi câu để nghe, nói theo 3 lần. Với hội thoại, bấm ▶ Nghe cả đoạn. Lần đọc thứ hai, bật 🙈 Làm mờ tiếng Việt ở thanh bên để tự dịch trong đầu trước khi xem nghĩa (chạm vào chữ mờ để hiện).


Commit message

Đừng nóiHãy nóiVì sao
❌ fixed bug✅ fix(auth): handle expired refresh tokensDạng mệnh lệnh, có phạm vi, mô tả cụ thể.
❌ update code✅ refactor(orders): extract price calculation into a service
❌ Added new feature for export✅ feat(export): add CSV export for order historyDùng "add", không "added".
❌ wip✅ chore: WIP – do not merge (squash before merging)Nếu bắt buộc phải commit dở.

Quy tắc: dòng đầu ≤ 72 ký tự, động từ nguyên mẫu (add, fix, remove, update, refactor, bump) — như thể hoàn thành câu If applied, this commit will ... . Dòng trống, rồi giải thích vì sao nếu cần.

PR description khiến reviewer duyệt nhanh

📄 Pull request template
## Why
Users with more than 10k orders get a timeout when exporting. (Fixes #1234)

## What
- Move CSV generation to a background job (Sidekiq)
- Send an email with a signed download link (expires in 24h)
- Add a "Preparing your export…" state in the UI

## How to test
1. Log in as `big-store@test.com` on staging
2. Go to Orders → Export
3. You should see the loading state and receive an email within ~2 minutes

## Risks / notes
- Adds a new queue `exports`; it needs to be added to the worker config before deploying.
- I didn't touch the Excel export — that's a follow-up (#1240).

## Screenshots
[before / after]

Code review: phân cấp và giọng điệu

NhãnÝ nghĩaVí dụ comment
nit:Chi tiết nhỏ, không bắt buộcnit: I'd rename this to isExpired for clarity.
suggestion:Đề xuất, tác giả tự quyếtsuggestion: we could use a map here instead of nested loops — it would make it O(n).
question:Hỏi để hiểu, không phải chêquestion: what happens if the API returns an empty list?
blocking: / issue:Phải sửa trước khi mergeblocking: this query runs inside the loop, so it'll cause N+1 queries in production.
praise:Khen điểm làm tốtpraise: really nice test coverage on the edge cases!
Comment review
Đừng nóiHãy nóiVì sao
❌ This is wrong.✅ I think this might break when the user has no orders — could you add a check?Nêu hậu quả cụ thể + đề xuất.
❌ Why didn't you use a hash map?✅ Have you considered using a hash map here? It might simplify the lookup."Have you considered" mềm hơn "Why didn't you".
❌ Change this.✅ What do you think about moving this into a helper? It's duplicated in three places.
❌ Bad naming.✅ nit: data2 is a bit hard to follow — maybe pendingOrders?
❌ You forgot tests.✅ Could we add a test for the expired-token case? That's the scenario that broke last time.Nói về code, không nói về người ("you forgot").
Phản hồi review
Mẫu câu tiếng AnhNghĩa & khi nào dùng
Good catch, thanks! Fixed in 3f2a1c9.Phát hiện hay, cảm ơn! Đã sửa ở commit 3f2a1c9.
Done.Đã làm (dùng cho nit nhỏ).
I went with X because ..., but I'm happy to change it if you feel strongly.Tôi chọn X vì ..., nhưng sẵn sàng đổi nếu anh thấy cần.
That's a fair point, but I'd prefer to keep it in this PR to avoid a second migration. Does that work for you?Hợp lý, nhưng tôi muốn giữ trong PR này để tránh migration thứ hai. Được không?
Good idea — I've created a follow-up ticket (#1250) so we don't block this PR.Ý hay — đã tạo ticket tiếp theo để không chặn PR này.
Could we jump on a quick call? I think it'll be faster than going back and forth here.Gọi nhanh nhé? Nhanh hơn trao đổi qua lại ở đây.

Bug report tái hiện được

📄 Bug report
Title: Checkout total is wrong when two coupons are applied

Environment: staging, v2.4.1, Chrome 128 / macOS
Severity: High — customers are overcharged

Steps to reproduce:
1. Add any two items to the cart
2. Apply coupon SAVE10, then coupon FREESHIP
3. Go to the payment step

Expected: Total = subtotal − 10% − shipping fee
Actual: Total = subtotal − 10% (shipping fee is still charged)

Frequency: 100% (5/5 attempts)
Logs / screenshots: [link]
Notes: Works correctly with a single coupon. Possibly related to PR #1180.

Email: BLUF và các câu mở/đóng

📄 Email báo cập nhật cho khách hàng (BLUF)
Subject: [Project Atlas] Release 2.5 moved to Thursday, Oct 30

Hi Sarah,

Bottom line: we're moving release 2.5 from Tuesday to Thursday, October 30.

During final testing, we found an issue with the payment provider's sandbox that we need to verify in production-like conditions. Everything else in the release is ready.

What this means for you:
- No impact on current users.
- The new reporting dashboard will be available two days later than planned.

Next steps: we'll send you a confirmation on Wednesday once testing is complete.

Please let me know if you have any questions or if Thursday causes problems on your side.

Best regards,
Minh
Tình huống😎 Thân mật (Slack, đồng nghiệp)🙂 Trung tính (meeting)🎩 Trang trọng (khách hàng, sếp lớn)
Mở đầuHey Tom,Hi Sarah,Dear Mr. Johnson,
Mục đíchQuick one —I'm writing to update you on ...I am writing with regard to ...
Đính kèmHere's the file.Please find the report attached.Please find attached the report for your review.
KếtCheers,Best, / Thanks,Kind regards, / Best regards,
Mời phản hồiLMK!Let me know if you have any questions.Please do not hesitate to contact me should you have any questions.

Tự kiểm tra

🧩 Tự kiểm tra: nói câu tiếng Anh trước, rồi mới mở đáp án
1 Commit: sửa lỗi timezone trong báo cáo

fix(reports): use the user's timezone when grouping by day

2 Review không bắt buộc: đặt tên biến rõ hơn

nit: maybe rename tmp to retryCount for clarity?

3 Review bắt buộc: lỗ hổng SQL injection

blocking: this builds the SQL string from user input, which opens us up to SQL injection. Could we use a parameterized query instead?

4 Phản hồi khi không đồng ý với review

I went with this approach because it avoids an extra network call, but I'm happy to change it if you feel strongly.

5 Tiêu đề email báo dời lịch release

[Project Atlas] Release 2.5 moved to Thursday, Oct 30

🏋️ Bài tập thực hành

Viết lại 5 sản phẩm chữ của chính bạn

(1) Viết lại 10 commit gần nhất theo Conventional Commits. (2) Viết lại PR description của PR gần nhất theo template. (3) Review một PR mã nguồn mở bất kỳ (chỉ viết nháp, không cần đăng) với ≥ 5 comment có nhãn. (4) Viết một bug report cho một lỗi thật bạn từng gặp. (5) Viết email BLUF báo trễ deadline. Nếu có trợ lý AI, hỏi: "Review my writing as a senior engineer at a US company. What sounds unnatural?"

🎙️ Phòng luyện nói

Chọn một đề, bấm ghi âm, nói 1-3 phút không nhìn ghi chú, rồi nghe lại. Tự chấm: rõ ý chưa? âm cuối có bật không? có dùng mẫu câu trong module không? Bản ghi chỉ nằm trên trình duyệt của bạn, không gửi đi đâu.

  1. Explain your last PR out loud as if you were walking a reviewer through it.
  2. Read your bug report aloud, then explain the expected vs. actual behaviour in your own words.
  3. Respond verbally to a reviewer who asked you to rewrite your solution, disagreeing politely.
0:00

📚 Tài nguyên học tập

✅ Tự đánh giá hoàn thành

  • Commit message mệnh lệnh, có phạm vi, ≤ 72 ký tự
  • PR description có Why / What / How to test / Risks
  • Comment review có nhãn và giọng xây dựng
  • Bug report có môi trường, bước tái hiện, kỳ vọng vs thực tế
  • Email theo BLUF với mức trang trọng phù hợp