17: Chỉ nên comment khi nào mà code không thể giải thích

Sự khác biệt giữa lý thuyết và thực tiễn trong thực tế lớn hơn rất nhiều so với trên lý thuyết — theo như quan sát thì điều này chắc chắn áp dụng với mọi comments. Trên lý thuyết, ý tưởng cơ bản của comment code nghe có vẻ hữu ích, như: cung cấp chi tiết hơn cho người đọc, giải thích về cái gì đang diễn ra. Còn điều gì có thể hữu ích hơn những điều này cơ chứ? Tuy nhiên, trong thực tế comment đôi khi lại trở thành một điều không tốt. Cũng như với bất kì hình thức viết nào khác, có một loại kỹ năng để viết tốt comments. ## lớn của kỹ năng đó là biết khi nào không nên viết chúng.

Khi code bị sai cú pháp, trình biên dịch, trình thông dịch và những tool khác chắc chắn sẽ báo lỗi. Nếu đoạn code theo một cách nào đó không chính xác về mặt chức năng, thì việc review, static analysis, testing, và sử dụng trong công việc hằng ngày sẽ văng hết các lỗi ra. Nhưng còn comments thì sao? Trong cuốn The **Elements of Programming Style (Computing McGraw-Hill)**​ của tác giả Kernighan và Plauger có viết rằng “Một comments sẽ có giá trị bằng 0 (thậm chí là số âm) nếu nó sai.” Và những bình luận như thế thường tạo thành rác và tồn tại bên trong codebase theo cách mà các lỗi mã hóa không bao giờ xảy ra. Chúng tạo cho chúng ta một nguồn gây xao lãng liên tục và cả thông tin sai lệch.

Nói thế nào khi mà những comment không sai về mặt kỹ thuật, nhưng lại không thêm chút giá trị nào cho đoạn code? Những comments như thế thực sự là vô dụng và thừa thãi. Comment lặp lại đoạn code nó chẳng cung cấp thêm thông tin gì cho người đọc đâu — tức là nói điều gì đó một lần bằng code và sau đó lặp lại bằng ngôn ngữ tự nhiên không làm nó đúng hơn hoặc chân thực hơn. Comment lặp lại như kiểu con vẹt không phải là một đoạn mã thực thi, nó không có tác dụng hữu ích cho người đọc hoặc thời gian chạy. Nó cũng trở nên cũ rất nhanh. Kể cả những comments liên quan đến phiên bản và những comments ghi chú cho code để cố gắng giải quyết các câu hỏi về phiên bản và lịch sử cập nhật. Comment làm gì khi mà những câu hỏi này đã được trả lời (hiệu quả hơn rất nhiều) bởi các công cụ quản lí phiên bản rồi.

Sự xuất hiện ngày càng nhiều của những comment mang tính dư thừa hoặc những comments mang thông tin sai lệch bên trong codebase đã dần làm cho các lập trình viên làm ngơ toàn bộ các comments, hoặc bỏ qua chúng, kể cả thực hiện các biện pháp tích cực nhằm che giấu chúng. Các lập trình viên họ rất sáng tạo và sẽ làm mọi cách để bỏ đi những gì họ cho rằng có thể sẽ gây ảnh hưởng đến hiệu suất công việc, ví dụ như: thu các comments lại; thay đổi lại màu sắc để các comments và background có màu giống nhau; dùng script để lọc bỏ các comments, vân vân và mây mây… mục đích là để “cứu” codebase từ những việc không nên làm của các lập trình viên gà mờ. Vì thế để giảm bớt khả năng bỏ lỡ những comments mang lại giá trị thực sự, comment nên được xem như thể chúng là code. Bằng cách mỗi comment nên thêm vào một vài giá trị cho người đọc, nếu không thì chúng chẳng khác gì là rác rưởi và đã là rác rưởi thì nên vứt đi hoặc là viết lại mà thôi.

Nói tóm lại, khi comment cần hạn chế những điều gì? Comments nên nói những điều mà code không nói ra được hoặc không thể nói. Một comment giải thích ý nghĩa của một đoạn code để sẵn sàng cho việc thay đổi cấu trúc đoạn code hoặc lập trình theo những quy ước chung để code có thể tự giải thích nghĩa cho chính nó. Thay vì dùng để giải thích cho những method hay class đặt tên dở, thì hãy đổi tên của chúng đi. Và thay vì comment từng phần từng phần trong những function dài ơi là dài thì hãy tách chúng ra thành những function nhỏ hơn sao cho tên của chúng vẫn giữ được những mục đích cũ. Hãy cố gắng diễn đạt càng nhiều càng tốt thông qua các đoạn code. Nếu có bất kỳ sự thiếu sót nào giữa việc diễn tả code hay diễn tả những nội dung mang tính bao quát tổng thể thì đây là lúc chúng ta nên comment. Comment những gì mà code không thể nói ra, nó không đơn giản là những gì code không nói được.