Login

Comment trong code: khi nào nên viết, khi nào là thừa

  • author-image

    Nguyễn Đình Cường

  • blog-tag
  • blog-comment 0 comment
  • created-date 09 Nov, 2026
blog-thumbnail

Người mới thường nghe hai lời khuyên mâu thuẫn: "hãy comment thật nhiều" và "code tốt không cần comment". Sự thật nằm ở giữa. Comment đúng chỗ là kho báu, còn comment sai chỗ là rác thậm chí gây hiểu lầm. Bài này giúp bạn phân biệt.

Nguyên tắc cốt lõi: code nói "cái gì", comment nói "vì sao"

Code tự cho biết nó đang làm gì, nếu được đặt tên tốt. Thứ code không thể nói là lý do đằng sau quyết định: ràng buộc nghiệp vụ, lỗi của thư viện, hay vì sao chọn cách này thay cho cách khác.

// Kém: lặp lại điều code đã nói// Tăng i lên 1i++;// Tốt: giải thích lý do// API đối tác giới hạn 100 request/phút, nên chờ 600ms giữa các lần gọiawait sleep(600);

Những comment nên viết

  1. Giải thích lý do (why): vì sao dùng thuật toán này, vì sao bỏ qua một trường hợp.
  2. Cảnh báo hệ quả: "Không đổi thứ tự các bước này, bước 2 phụ thuộc kết quả bước 1".
  3. Giải thích quy tắc nghiệp vụ khó đoán: "Khách hàng đăng ký trước 2020 được giữ mức phí cũ theo hợp đồng".
  4. Ghi chú workaround: "Tạm thời bù lỗi của thư viện X phiên bản 2.3, xem issue #456".
  5. Tài liệu hóa API công khai: docstring, JSDoc, PHPDoc cho hàm/class mà người khác dùng.
  6. Giải thích regex hoặc công thức phức tạp khi không thể làm gì để đơn giản hơn.
  7. TODO có ngữ cảnh: "TODO: bỏ khi chuyển sang API v2" kèm tên hoặc mã ticket.

Những comment nên tránh

  • Comment nhắc lại code: // lấy danh sách người dùng ngay trên getUsers().
  • Comment lỗi thời: code đã đổi nhưng comment vẫn cũ, tệ hơn không có comment vì nó đánh lừa người đọc.
  • Code bị comment lại: hàng chục dòng code cũ nằm lại "phòng khi cần". Đã có Git, hãy xóa đi.
  • Nhật ký thay đổi trong file: "// sửa bởi An ngày 3/5" nên để Git lo (git log, git blame).
  • Comment làm cớ cho tên tồi: int d; // số ngày trôi qua, hãy đặt tên elapsedDays.
  • Ngôn từ cảm xúc hoặc đùa cợt: "// đừng hỏi tại sao, nó chạy được" không giúp được ai.

Ví dụ: biến comment thành tên hàm

// Trước// Kiểm tra người dùng đủ 18 tuổi và đã xác minh emailif (user.age >= 18 && user.emailVerifiedAt !== null) {allowPurchase();}// Saufunction canPurchase(user) {return user.age >= 18 && user.emailVerifiedAt !== null;}if (canPurchase(user)) {allowPurchase();}

Đoạn comment biến mất vì tên hàm đã nói thay. Đây là cách xử lý tốt nhất: nếu cảm thấy cần comment để giải thích code, hãy thử đổi tên hoặc tách hàm trước.

Docstring cho API công khai

Với hàm hoặc class mà người khác sẽ gọi, tài liệu ngắn gọn là cần thiết, vì người dùng không muốn đọc ruột của nó. Ví dụ trong Python:

def calculate_tax(amount, rate):"""Tính tiền thuế.amount: số tiền trước thuế (VND).rate: thuế suất dạng thập phân, ví dụ 0.1 cho 10%.Trả về số tiền thuế, đã làm tròn đến đơn vị đồng."""return round(amount * rate)

Giữ docstring ngắn, nêu mục đích, tham số, giá trị trả về và các ngoại lệ đáng chú ý.

Giữ comment luôn đúng

  • Khi sửa code, đọc lại comment gần đó và cập nhật hoặc xóa.
  • Khi review code, kiểm tra xem comment có còn khớp với hành vi không.
  • Ưu tiên comment ngắn và sát đoạn code liên quan, vì comment xa dễ bị lãng quên.
  • Đặt tài liệu dài (kiến trúc, cách cài đặt) vào README hoặc wiki thay vì nhồi vào đầu file.

Ngôn ngữ nào cho comment?

Hãy theo quy ước của nhóm. Với dự án mã nguồn mở hoặc có thành viên nước ngoài, dùng tiếng Anh. Với nhóm toàn người Việt, dùng tiếng Việt có dấu cũng hoàn toàn chấp nhận được, miễn là nhất quán và dễ hiểu. Cái quan trọng là giải thích rõ ràng, không phải ngôn ngữ nào.

Kết luận

Trước khi viết comment, hãy tự hỏi: nếu đổi tên hoặc tách hàm thì có cần comment này không? Nếu vẫn cần và nó giải thích lý do, hãy viết ngắn gọn và giữ cho nó luôn đúng. Ít comment nhưng giá trị sẽ tốt hơn nhiều comment vô nghĩa.

Học cách viết code rõ ràng cùng bài tập thực hành có thể bắt đầu từ các khóa học trên codebem.com.

author_photo
Nguyễn Đình Cường

0 comment