Viết comment vào source code như thế nào cho hiệu quả, tránh thiếu cũng như dư thừa không cần thiết? Với mong muốn chia sẻ về cách xác định xem trường hợp nào cần viết và cách thức viết comment, bài viết dưới đây sẽ giới thiệu về các quy tắc và lưu ý khi viết comment.
Mục đích của viết comment code nhằm truyền đạt ý đồ của người viết code cho người đọc code. Mỗi khi viết ra một hàm hay một class nào đó, người viết code sẽ có những suy nghĩ, nhận định của bản thân với những dòng code được viết ra. Những suy nghĩ đó sẽ giúp cho việc đọc hiểu của người tiếp nối thuận lợi hơn nếu được truyền đạt một cách ngắn gọn, dễ hiểu và đầy đủ. Ở bài viết này, chúng ta sẽ tìm hiểu về các mục sau khi viết comment code:
- Những trường hợp không cần viết comment code
- Ghi lại những suy nghĩ của bản thân khi đang viết code
- Suy nghĩ ở vị trí của người đọc code để hiểu mình cần comment nội dung gì
I. Những trường hợp không cần viết comment
Chúng ta hãy xem xét ví dụ dưới đây:
Như các bạn đã thấy ở trên, những comment đó không cung cấp thêm thông tin giúp người đọc code đọc nhanh hơn. Vì vậy cần lưu ý, không comment vào các nội dung mà chỉ cần đọc code là có thể hiểu ngay được.
I.1. Không comment chỉ để giữ quy tắc
Có những nơi quy định bắt buộc phải viết comment đầy đủ cho mỗi function hay class được viết. Nên có những trường hợp như sau:
I.2. Hãy sửa nếu tên không diễn đạt đủ ý nghĩa thay vì comment vào chỉ để giải thích
Nếu nhìn qua tên thì ai cũng nghĩ ngay rằng Delete Registry là hàm phải rất cẩn trọng khi sử dụng vì dùng không cẩn thận có thể xóa mất Registry, tuy nhiên đọc comment thì nó không gây ảnh hưởng đến Registry. Thay vì comment vào như thế, chúng ta nên lấy một cái tên đẹp hơn cho function này
II. Ghi lại những suy nghĩ của bản thân khi đang viết code
II.1. Comment tổng quan
Với mỗi class hay function phức tạp chúng ta nên viết giới thiệu hay thuyết minh tổng quan cho chúng để người đọc có cái nhìn bao quát và đi nhanh hơn trong quá trình đọc chi tiết. Những vấn đề trong source code cần giải quyết. Ví dụ như:
II.2. Comment vào những điểm còn khúc mắc và chưa được thực hiện
Những phần này có cú pháp phần mở đầu phân theo từng mục đích:
TODO: Để sau làm
FIXME: Hiện tại đang có lỗi
HACK: Cách làm chưa được tốt lắm, cần cải tiến
XXX: Nguy hiểm, có vấn đề lớn
Tuỳ từng tổ chức mà có thể thay đổi cú pháp cho phù hợp, ví dụ như vấn đề lớn cần làm thì viết HOA toàn bộ “TODO:” , vấn đề nhỏ thì viết thường “todo:”
II.3. Comment cho hằng số
Với hằng số, chúng ta nên comment để người đọc hiểu tại sao nên chọn giá trị đó. Khi ấy việc chỉnh sửa sẽ nhanh và dễ dàng hơn rất nhiều.
III. Comment code đứng ở lập trường của người đọc
Một số lưu ý khi thực hiện comment code tạo điều kiện cho người đọc code dễ dàng tiếp nhận thông tin hơn:
– Dự tính trước các thắc mắc người đọc gặp
– Thông báo trước các cạm bẫy có thể gặp phải gây hiểu lầm trong quá trình đọc
– Viết comment tổng quan ngắn gọn, đảm bảo đủ ý nghĩa
IV. Vượt qua trở ngại khi bắt đầu viết comment code
03 bước để có một comment code nhanh chóng và hiệu quả:
- Viết ra ngay suy nghĩ trong đầu
- Xem lại câu cú xem cần sửa chữa chỗ nào
- Tiến hành sửa
- Tổng kết
Trên đây là giới thiệu cơ bản về cách viết những comment code tối ưu hiệu quả. Hy vọng sẽ giúp các bạn áp dụng vào công việc của mình tốt hơn.
Nguồn: Viblo