Trong lập trình, code không chỉ là một tập hợp các câu lệnh để máy tính thực thi, mà còn là một hình thức giao tiếp giữa các lập trình viên. Dù code có thể rõ ràng và dễ hiểu với chính người viết, nhưng với những người khác, hoặc thậm chí chính chúng ta trong tương lai, code có thể trở nên khó hiểu và mơ hồ. Chính vì vậy, việc sử dụng comment đúng cách là một phần quan trọng trong việc giữ cho code luôn sạch sẽ và dễ bảo trì.
1. Bổ sung thông tin cho code
Comment trong code có tác dụng quan trọng trong việc bổ sung thông tin, làm cho code trở nên dễ hiểu và dễ duy trì hơn. Khi có thêm comment, người đọc sẽ nhanh chóng nắm được thông tin thay vì phải tự phân tích.
Ta có ví dụ sau:
Nếu không có comment sau thì người đọc rất khó hình dung được tác dụng của biểu thức chính quy và tốn thời gian tìm hiểu. Nhưng chỉ với một dòng comment thì mọi thứ đã được giải quyết.
2. Bổ sung thông tin cho công việc
Comment có thể được sử dụng trong một số tình huống khác để người đọc biết được các công việc mà tác giả đã hoặc sẽ thực hiện:
+ Những việc cần xử lý trong tương lai cho một hàm hay một class.
+ Cảnh báo về việc sử dụng một hàm có thể tạo ra những tác động không mong muốn như thế nào.
+ Giải thích về lý do lựa chọn phương án này thay vì phương án khác trong trường hợp có nhiều phương án được biết đến.
+ Giải thích cho việc lựa chọn giá trị cho hằng và biến bằng giá trị nào đó thay vì một giá trị khác.
Ta có các ví dụ sau:
Ghi chú công việc cho tương lai
Cảnh báo về tác động không mong muốn khi sử dụng hàm
Giải thích lý do chọn phương án này thay vì phương án khác
Giải thích lý do chọn giá trị cho hằng hoặc biến
3. Không dùng comment nếu có thể
Hãy cố gắng đặt tên biến và sử dụng class với tên gợi nhớ và có ý nghĩa để có thể không cần dùng comment mà người đọc vẫn có thể hiểu được.
Thay vì thêm comment để giải thích, hãy sử dụng tên biến, tên hàm, và tên class sao cho chúng tự miêu tả được mục đích và chức năng của chúng.Comment dễ bị lỗi thời khi mã thay đổi, và chúng thường không được cập nhật cùng với mã, gây hiểu nhầm cho người đọc.
4. Bỏ các comment thừa
Có một số loại comment thừa cần được loại bỏ trong chương trình của chúng ta:
+ Comment cho các đoạn code không dùng nữa hoặc với ý định là sau này sẽ dùng lại khi cần.
+ Comment cho các tham số của hàm mà ngay khi đọc tên và kiểu dữ liệu của tham số ta đã biết được ý nghĩa của nó, và comment đó không cung cấp thêm thông tin gì khác.
+ Comment để lưu lại sự thay đổi theo theo từng lần chỉnh sửa của file.
Kết luận
Nguyên tắc viết comment trong Clean Code nhấn mạnh rằng mã nguồn rõ ràng và có cấu trúc tốt nên hạn chế tối đa việc sử dụng comment. Theo đó, thay vì dựa vào comment để giải thích, lập trình viên nên tập trung vào việc viết mã sao cho tự giải thích thông qua tên biến, tên hàm, và cấu trúc mã hợp lý. Comment chỉ nên được sử dụng khi thật sự cần thiết, như để giải thích ý đồ phức tạp, các giả định quan trọng hoặc các tình huống đặc biệt không thể truyền tải rõ ràng qua mã.
