Skip to content

Clean Code — Viết mã nguồn dễ kiểm thử (Testability) và bài học thực tế

IT ~1990 từ
Clean Code — Viết mã nguồn dễ kiểm thử (Testability) và bài học thực tế

Nguyên tắc cốt lõi từ Robert C. Martin về việc giữ cho mã nguồn trong sáng, hàm đơn nhiệm và cách thiết kế module giúp việc kiểm thử trở nên dễ dàng.

01Giới thiệu — Clean Code là gì và tại sao nó quan trọng?

Clean Code: A Handbook of Agile Software Craftsmanship xuất bản năm 2008 bởi Robert C. Martin — hay còn được cộng đồng lập trình gọi thân mật là Uncle Bob — là một trong những cuốn sách kỹ thuật phần mềm được đọc nhiều nhất thế giới. Uncle Bob không chỉ là tác giả mà còn là đồng sáng lập của Agile Manifesto và là người đặt nền móng cho nhiều nguyên tắc thiết kế hiện đại như SOLID.

Ý tưởng trung tâm của cuốn sách rất đơn giản: code được đọc nhiều hơn là được viết. Mỗi lần một kỹ sư mở một file để sửa lỗi hay thêm tính năng mới, họ phải đọc và hiểu code cũ trước. Nếu code đó rối rắm, đặt tên mơ hồ, hàm dài hàng trăm dòng — chi phí nhận thức (cognitive cost) tăng lên đáng kể, kéo theo tốc độ phát triển chậm lại và số lượng lỗi phát sinh tăng cao.

Với tôi, là một QA Engineer, Clean Code không chỉ là vấn đề thẩm mỹ code hay phong cách cá nhân. Nó ảnh hưởng trực tiếp đến khả năng kiểm thử của hệ thống — một hệ thống được viết tốt sẽ dễ viết test hơn, dễ tìm lỗi hơn và dễ dự đoán hành vi hơn.

02Tên biến và hàm có ý nghĩa — Nền tảng của mọi thứ

Chương đầu tiên của Clean Code dành toàn bộ cho việc đặt tên — và đây không phải ngẫu nhiên. Một cái tên tốt là tài liệu tự giải thích (self-documenting). Nó cho người đọc biết cái này là gì và nó dùng để làm gì mà không cần đọc thêm bất kỳ dòng nào khác.

So sánh hai đoạn code sau (TypeScript/NestJS):

// ❌ Tên mơ hồ — người đọc không biết d là gì, flag làm gì
function process(d: any, flag: boolean) { ... }

// ✅ Tên rõ ràng — ý định lộ ra ngay từ chữ ký hàm
function processBookingPayment(booking: Booking, isSandboxMode: boolean) { ... }

Trong kiểm thử, tên quan trọng hơn nữa. Khi một test case thất bại, cái tên của test phải giải thích ngay được tình huống nào đang được kiểm tra. Tên như test1() hay shouldWork() là vô nghĩa khi CI pipeline báo đỏ lúc 2 giờ sáng. Một tên tốt như should_return_404_when_seat_is_already_booked() giúp cả team hiểu ngay vấn đề mà không cần đọc code bên trong.

03Single Responsibility Principle — Một hàm, một nhiệm vụ

Uncle Bob phát biểu nguyên tắc SRP đơn giản: "A function should do one thing, and do it well." Một hàm nên làm một việc duy nhất, làm tốt việc đó và chỉ làm việc đó mà thôi.

"Functions should do one thing. They should do it well. They should do it only." — Robert C. Martin

Từ góc nhìn kiểm thử, SRP ảnh hưởng trực tiếp đến test isolation. Khi một hàm thực hiện nhiều bước — validate input, truy vấn database, gửi email thông báo và ghi log — bạn không thể viết unit test cho từng hành vi riêng lẻ. Mỗi test phải setup toàn bộ ngữ cảnh, dẫn đến test chậm, giòn (fragile) và khó maintain.

Khi hàm được tách nhỏ theo đúng trách nhiệm, mỗi phần có thể được kiểm thử độc lập với mock/stub. Ví dụ: hàm validateSeatAvailability() chỉ kiểm tra logic nghiệp vụ thuần túy, không cần kết nối database thật, nên test chạy trong micro-giây và kết quả hoàn toàn dự đoán được.

04Hàm ngắn và trong sáng — Bao nhiêu dòng là đủ?

Clean Code đề xuất hàm nên rất ngắn — lý tưởng nhất là từ 5 đến 15 dòng. Nghe có vẻ cực đoan, nhưng mục tiêu là giảm cognitive complexity: số lượng trạng thái mà não người phải theo dõi khi đọc một đoạn code.

Nested if/else nhiều tầng, vòng lặp lồng nhau, điều kiện phức tạp — tất cả đều là dấu hiệu của cognitive complexity cao. Công cụ như SonarQube có thể đo chỉ số này và cảnh báo khi một hàm vượt ngưỡng cho phép. Từ góc độ QA, hàm có cognitive complexity cao đồng nghĩa với việc cần viết nhiều test case hơn để bao phủ đủ các nhánh (branch coverage).

Một quy tắc thực tế: nếu bạn cần cuộn chuột để đọc hết một hàm, đó là dấu hiệu cần refactor. Nếu bạn phải đọc hàm nhiều hơn một lần để hiểu nó làm gì, cognitive complexity đang quá cao.

05Comment — Mùi thối hay tài sản?

Đây là một trong những quan điểm gây tranh cãi nhất của Clean Code: comment thường là dấu hiệu của code tệ. Lập luận của Uncle Bob là nếu bạn cần comment để giải thích code đang làm gì, vấn đề nằm ở code — không phải ở sự thiếu comment.

Trong thực tế, comment có giá trị nhất trong các test case — giải thích tại sao một scenario được chọn, hoặc mô tả edge case phức tạp mà tên hàm không thể truyền tải đủ.

06Testability và thiết kế module — Code khó test là code khó maintain

Đây là luận điểm trung tâm nhất của bài viết này: testability không phải là tính năng thêm vào sau — nó là chỉ báo chất lượng thiết kế. Nếu bạn không thể viết unit test cho một module mà không cần khởi tạo toàn bộ hệ thống, module đó đang vi phạm nguyên tắc thiết kế cơ bản.

Giải pháp chính là Dependency Injection (DI) — thay vì để hàm tự khởi tạo dependency bên trong (hard-coded dependency), dependency được truyền từ bên ngoài vào. NestJS áp dụng DI rất sâu, và đây là lý do tại sao việc viết unit test trong NestJS tương đối dễ dàng:

// ❌ Hard dependency — không thể mock BookingRepository trong unit test
class BookingService {
  private repo = new BookingRepository(); // phụ thuộc cứng
  async getBooking(id: string) { return this.repo.findById(id); }
}

// ✅ Dependency Injection — dễ dàng inject mock trong test
@Injectable()
class BookingService {
  constructor(private readonly repo: BookingRepository) {}
  async getBooking(id: string) { return this.repo.findById(id); }
}

Với DI, trong test bạn chỉ cần inject một mock repository: { provide: BookingRepository, useValue: mockRepo }. Test chạy không cần database, không cần network — nhanh và đáng tin cậy.

07Error Handling rõ ràng — Đừng nuốt lỗi

Clean Code dành hẳn một chương cho error handling với thông điệp rõ ràng: đừng bao giờ nuốt lỗi im lặng. Một try-catch trống rỗng hay chỉ console.log(err) rồi tiếp tục là công thức tạo ra các bug ma (phantom bug) — lỗi xảy ra nhưng không để lại dấu vết nào.

Với QA, error handling tốt có nghĩa là: khi test scenario lỗi (negative test case), hệ thống trả về đúng HTTP status code, đúng error message, và log đầy đủ thông tin để debug — không phải một 500 Internal Server Error vô nghĩa.

08Áp dụng thực tế — Refactor giúp viết test dễ hơn thế nào?

Trong dự án movie-booking (NestJS/TypeScript), tôi từng gặp một hàm bookSeat() dài hơn 80 dòng, xử lý đồng thời: validate input, kiểm tra ghế trống, tính giá (bao gồm discount và tax), charge payment, lưu booking, gửi email xác nhận và publish event lên message queue.

Việc viết unit test cho hàm này gần như bất khả thi mà không setup toàn bộ infrastructure. Sau khi refactor theo nguyên tắc SRP, hàm được tách thành một pipeline nhỏ:

Kết quả: từ 0 unit test có thể viết được, chúng tôi có 23 unit test riêng lẻ với coverage >90% cho business logic, mỗi test chạy dưới 5ms. Khi một test fail, chúng tôi biết ngay chính xác bước nào bị lỗi mà không cần debug từ đầu.

09Bẫy over-engineering — Clean Code ≠ Design Patterns ở mọi nơi

Một trong những hiểu nhầm phổ biến nhất về Clean Code là nó yêu cầu áp dụng Factory Pattern, Strategy Pattern, Observer Pattern... ở khắp nơi. Thực tế hoàn toàn ngược lại.

Uncle Bob nhấn mạnh nguyên tắc YAGNI — You Aren't Gonna Need It: đừng thêm abstraction, interface, hay pattern cho những thứ bạn chưa thực sự cần. Mỗi lớp abstraction thêm vào là chi phí nhận thức và là điểm tiềm ẩn lỗi mới. Code đơn giản nhất giải quyết được vấn đề hiện tại mới là code tốt nhất — không phải code phức tạp nhất.

"Simple is better than complex. Complex is better than complicated." — The Zen of Python (nhưng đúng với mọi ngôn ngữ)

Trong thực tế kiểm thử, over-engineering làm hại test coverage không kém gì code rối. Một class sử dụng 5 tầng abstraction để xử lý một nghiệp vụ đơn giản sẽ cần 5 lớp mock tương ứng — test trở nên phức tạp hơn cả code cần test. Đây là dấu hiệu rõ ràng rằng thiết kế đang có vấn đề.

10Kết luận — Clean Code là đầu tư dài hạn cho cả Dev lẫn QA

Sau nhiều tháng áp dụng các nguyên tắc từ Clean Code vào thực tế — cả khi viết code lẫn khi review và kiểm thử — tôi đi đến kết luận: mã nguồn sạch không phải là xa xỉ phẩm, mà là điều kiện cần thiết để phát triển phần mềm bền vững.

Với developer, code sạch giúp giảm thời gian debug, dễ onboard thành viên mới và giảm technical debt tích lũy. Với QA engineer, code sạch có nghĩa là: test dễ viết hơn, coverage cao hơn, bug được phát hiện sớm hơn và — quan trọng nhất — lỗi khi xảy ra sẽ rõ ràng hơn rất nhiều.

Không có đội ngũ nào có đủ thời gian để viết test cho mọi dòng code xấu. Nhưng khi code được thiết kế tốt ngay từ đầu, việc kiểm thử trở thành một phần tự nhiên của quy trình thay vì một gánh nặng bổ sung. Đó chính là lý do tôi tin rằng mọi QA engineer đều nên đọc Clean Code — không chỉ để hiểu developers đang nói gì, mà để trở thành người advocate tốt hơn cho chất lượng phần mềm từ gốc rễ.