Clean code series: Part 4 - Comments
1. Comment trong lập trình là gì?
Comment là một dòng hoặc nhiều dòng văn bản, được chèn vào source code chương trình, nhằm làm cho source code trở nên dễ hiểu hơn với người đọc, được bỏ qua bởi trình biên dịch.
Cú pháp comment.
Tuỳ từng ngôn ngữ có những cách comment riêng.
Nhưng thường có 2 cách chính là:
- Comment 1 dòng
- Comment nhiều dòng
2. Bad comment.
Comment thừa:
Những comment như thế này là những comment không có ý nghĩa, đôi khi có làm gián đoạn hay khó chịu với người đọc.
- ví dụ như hình ảnh bên trên ai cũng có thể hiểu rằng đang gán giá trị smallestIndex = 0 nhưng vẫn có dòng comment bên trên.
Comment gây nhiễu, sai sự thật.
- Hàm bên trên sẽ kiểm tra 1 chuỗi truyền vào có ít nhất 1 ký tự nhưng comment phía trên đã phản ánh sai chức năng của hàm. Nó có thể gây khó khăn cho người code sau khi đọc comment.
Commented-OutCode.
- Đó là những comment như thế nào. Đó là những comment không được chạy nhưng vẫn được comment kiểu như thế này:
Thông tin phi tập trung
Nếu bắt buộc phải viết một comment, hãy đảm bảo rằng nó giải thích cho phần code gần nó nhất. Đừng cung cấp thông tin của toàn bộ hệ thống trong một comment cục bộ.
3. Good comment.
Comment liệu có cần thiết
Nhận xét nên hạn chế được đưa vào code, tuy nhiên dưới đây là một số good comment bạn nên đưa vào để bổ sung các thông tin hữu ích cho các đoạn code của bạn.
Legal Comments: Comment về pháp lý
Đôi khi tiêu chuẩn mã hoá doanh nghiệp buộc chúng ta phải viết một số comment nhât định vì lý do pháp lý.
Comment cung cấp thông tin.
Cung cấp thông tin cơ bản với một vài dòng comment đôi khi rất hữu ích. (chẳng hạn đầu vào, đầu ra)
Làm cho code dễ hiểu hơn
Comment để diễn giải ý nghĩa của các đối số khó hiểu hoặc giá trị trả về, để biến chúng thành thứ gì đó có thể hiểu được
Todo Comment.
Đó là comment các công việc bạn chưa kịp thực hiện hoặc các chức năng bạn có thể phát triển trong tương lai:
4. Kết luận.
“Đừng biến đống code gớm ghiếc của bạn thành comment - hãy viết lại nó”
- Cần tránh những comment quá vô dụng hoặc sai sự thật.
- Nên comment khi thực sự nó giúp ích cho việc đọc và hiểu code dễ dàng hơn.