Clean Code — Phần 2: Comment và Formatting

Comment: Khi nào cần, khi nào không?

Robert C. Martin cho rằng comment tốt nhất là comment không cần viết. Code nên tự giải thích được ý nghĩa của nó.

Comment tốt

• Legal comment: Copyright, license
• Informative comment: Giải thích regex phức tạp
• TODO comment: Đánh dấu việc cần làm

Comment xấu

• Redundant comment: Lặp lại điều code đã nói
• Misleading comment: Thông tin sai hoặc lỗi thời
• Commented-out code: Code bị comment out nhưng không xóa

// Bad - comment thừa
// Increment counter by 1
counter++;

// Good - comment giải thích lý do
// We use a 30-second timeout because the external API
// has a documented p99 latency of 25 seconds
const TIMEOUT_MS = 30_000;

Formatting

Code formatting ảnh hưởng trực tiếp đến khả năng đọc hiểu.

Vertical Formatting

• Khoảng cách: Nhóm các đoạn code liên quan lại
• Mật độ: Code liên quan gần nhau, code không liên quan xa nhau
• Thứ tự: Hàm gọi trước, hàm được gọi sau

Horizontal Formatting

• Độ rộng: Giữ dòng dưới 120 ký tự
• Indentation: Nhất quán tab hoặc space
• Alignment: Không cần căn chỉnh theo cột

Kết luận phần 2

Comment chỉ nên dùng khi code không thể tự giải thích. Formatting nhất quán giúp team làm việc hiệu quả hơn.