Series Clean Code Thực chiến #3: Sự thật phũ phàng về Comment – Khi dòng code "biết nói"

1. Tại sao Comment lại là "Kẻ nói dối"?

Mã nguồn (Code) là sự thật duy nhất, vì máy tính chỉ chạy code. Comment (Bình luận) chỉ là những dòng chữ hiển thị cho con người.

Khi hệ thống AFC Metro thay đổi logic nghiệp vụ, lập trình viên sẽ lao vào sửa code để đáp ứng deadline. Và 90% trường hợp, họ quên cập nhật lại comment. Sau vài tháng, code làm một đằng, comment nói một nẻo. Người đồng nghiệp (hoặc chính bạn) vào đọc comment, tin tưởng nó, và cuối cùng tạo ra một con bug phá hỏng hệ thống.

Đó là lý do Uncle Bob nói: Một comment sai lệch còn nguy hiểm hơn là không có comment nào.

2. Đừng giải thích Code tệ, hãy viết lại nó!

Lý do phổ biến nhất mà chúng ta viết comment là vì đoạn code đó quá tối nghĩa và phức tạp. Thay vì cố gắng viết một đoạn văn dài để giải thích, hãy dùng thời gian đó để Refactor (Tái cấu trúc) lại mã nguồn.

Bad Code (Dùng comment để chữa cháy):

// Kiểm tra xem vé có đủ điều kiện để đi qua trạm kiểm soát không
// Trạng thái 1 là kích hoạt, loại 3 là vé VIP, time > 0 là còn hạn
if ($ticket->status == 1 && $ticket->type == 3 && $ticket->expired_at > now()) {
    $this->openGate();
}

Người đọc phải căng mắt ra đối chiếu từng điều kiện với dòng comment.

Clean Code (Code tự nói lên tất cả):

Bằng cách gom nhóm logic vào một hàm hoặc phương thức có tên rõ ràng, bạn hoàn toàn có thể xóa bỏ dòng comment kia đi.

if ($ticket->isValidVipTicket()) {
    $this->openTurnstile();
}

// Bên trong class Ticket:
public function isValidVipTicket(): bool {
    return $this->isActive() && $this->isVip() && !$this->isExpired();
}

Code lúc này đọc trơn tru như tiếng Anh cơ bản. Không cần bất kỳ dòng giải thích nào.

3. Những Comment "bốc mùi" cần xóa ngay lập tức

Khi review code, nếu thấy những loại comment này, bạn hãy thẳng tay xóa đi để làm sạch bộ nhớ ngữ cảnh của team:

• Comment lải nhải (Redundant): Giải thích những thứ quá hiển nhiên.

$i++; // Tăng i lên 1
$user = User::find($id); // Tìm user theo ID

• Nhật ký sửa đổi (Journal Comments): ```php // 2026-05-10: Hoàng Nguyễn đã thêm đoạn fix lỗi timeout với Vitess // 2026-06-01: Cập nhật lại logic vì sếp đổi ý

Thời đại này chúng ta dùng Git. Nếu muốn xem ai sửa, sửa ngày nào, lý do là gì, cứ gõ `git blame` hoặc xem lịch sử commit. Đừng biến file code thành bãi rác lịch sử.

• "Nghĩa trang" Code bôi xanh (Commented-out Code): Đây là thói quen xấu nhất của dân Dev. Sợ xóa nhầm nên bấm Ctrl + / để "tạm cất" đoạn code cũ đi. Những đoạn code chết này sẽ cứ nằm đó vĩnh viễn vì người đến sau không dám xóa (sợ có ẩn ý gì đó). Hãy tự tin XÓA NÓ ĐI! Git lưu lại toàn bộ lịch sử, nếu cần bạn có thể móc lại dễ dàng.

4. Khi nào thì Comment được coi là "Code Sạch"?

Nói vậy không có nghĩa là chúng ta cấm tiệt việc dùng comment. Có những tình huống mà mã nguồn không thể tự nó diễn đạt được bối cảnh. Đó là lúc comment phát huy tác dụng:

• Giải thích các Biểu thức chính quy (Regex): Không ai có thể đọc hiểu Regex ngay lập tức được.

// Bắt định dạng chuẩn của thẻ RFID: Bắt đầu bằng 2 chữ cái, theo sau là 8 chữ số
$pattern = '/^[A-Z]{2}\d{8}$/';

• TODO Comments: Đánh dấu những việc cần làm nhưng hiện tại chưa có thời gian xử lý hoặc chờ API của bên thứ 3 (ví dụ chờ vendor Hitachi cập nhật firmware).

// TODO: Hiện tại đang giả lập dữ liệu offline. Sẽ tích hợp RabbitMQ để sync real-time vào Q3/2026.

• Cảnh báo hậu quả (Warning):

// CẢNH BÁO: Đừng xóa hàm sleep(2) này. 
// API của ngân hàng đối tác sẽ chặn IP của chúng ta nếu gọi dồn dập quá 2 request/giây.
sleep(2);

• Nghiệp vụ "phi logic" (Business Rule): Khi logic code có vẻ vô lý, nhưng đó lại là yêu cầu khắt khe của bộ phận Vận hành. Nếu không có comment, đồng nghiệp sẽ tưởng bạn code sai và tự ý sửa lại.

Tóm lại: Hãy coi Comment như một "loại thuốc đắng". Chỉ dùng khi thực sự cần thiết để chữa bách bệnh cho những đoạn logic không thể diễn đạt bằng code. Trong 90% thời gian làm việc, hãy dành nỗ lực vào việc đặt tên biến và tách hàm. Một khi mã nguồn của bạn trong suốt, nó sẽ không cần bất kỳ một người phiên dịch nào cả!