9 phương pháp hay nhất để viết code comment

Trong khi có nhiều tài nguyên để giúp các lập trình viên viết code tốt hơn, chẳng hạn như sách và các công cụ phân tích, thì lại có rất ít tài nguyên liên quan đến code comment. Mặc dù rất dễ để đo lường số code comment trong một chương trình lập trình, nhưng rất khó để đo lường chất lượng của chúng. Vì thế, trong bài viết dưới đây FUNiX sẽ gợi ý cho bạn 9 quy tắc để viết code comment tốt hơn.

1. Quy tắc 1: Comment không được trùng lặp với code

Lập trình viên thường viết quá nhiều code comment bởi vì những người hướng dẫn khuyên họ làm như vậy. Một số học viên trong các lớp khoa học máy tính có thói quen thêm một code comment vào mỗi dấu ngoặc nhọn như một dấu hiệu cho biết  block nào đang kết thúc:

Một số giảng viên yêu cầu sinh viên viết code comment vào từng dòng mã. Tuy nhiên, các code comment đó không bổ sung thêm thông tin có ý nghĩa phủ định mà ngược lại, chúng đem đến một số phiền toái như:

• Khiến bộ code trở nên lộn xộn về mặt trực quan
• Khiến lập trình viên phải dành thêm thời gian để viết và đọc code
• Code comment có thể không còn ý nghĩa ở thời điểm khác trong tương lai

Trường hợp về code comment không cần thiết là:

Nó không thêm bất kỳ thông tin nào giá trị nào mà khiến phát sinh thêm chi phí bảo trì.

2. Quy tắc 2: Comment tốt không bào chữa cho các code không rõ ràng

Một cách sử dụng sai khác của code comment là cung cấp thông tin mà lẽ ra phải được ghi trong code. Một ví dụ đơn giản là khi lập trình viên đặt tên cho một biến bằng một chữ cái và sau đó thêm chú thích mô tả mục đích của nó:

Sẽ tốt hơn nếu lập trình viên đặt tên biến rõ ràng để không cần thêm code comment sau đó:

Như Kernighan và Plauger đã viết trong “The Elements of Programming Style”: “ “Don’t comment bad code — rewrite it” (Đừng nhận xét code xấu – hãy viết lại nó).

3. Quy tắc 3: Comment không rõ ràng sẽ gây ra lỗi với code

Nhận xét nổi tiếng nhất trong “Unix source code”: “Bạn không nên hiểu điều này”,  khi phải đối mặt với một số code chuyển đổi rườm rà. Điều này làm gợi nhớ đến Luật của Kernighan: “Gỡ lỗi khó gấp đôi so với việc viết code cẩn thận ngay từ đầu. Do đó, nếu bạn đã viết code một cách tốt nhất có thể, thì theo luật trên, bạn sẽ không đủ thông minh để gỡ lỗi nó”. Vì vậy, hãy viết lại code theo cách mà bạn hiểu và có thể giải thích lại cho người khác.

>>> Xem thêm tại: Bí quyết để bạn vượt trội trong nghề lập trình viên

4. Quy tắc 4: Comment phải xóa bỏ được sự nhầm lẫn

Sẽ không có cuộc thảo luận nào về những code comment xấu nếu không có câu chuyện từ Steven Levy’s Hackers – “Heroes of the Computer Revolution”:

Peter Samson đã từ chối thêm nhận xét vào code nguồn của mình để giải thích cho những gì anh ta đã viết. Chương trình mà Samson đã viết tiếp tục được phân phối cho hàng trăm hướng dẫn viết bằng hợp ngữ, chỉ với một nhận xét bên cạnh một lệnh chứa số 1750. Nhận xét đó là “RIPJSB” và mọi người phải vắt óc suy nghĩ về ý nghĩa của nó. Mãi đến khi ai đó phát hiện ra rằng năm 1750 là năm Bach qua đời, và Samson đã viết tắt “Rest In Peace Johann Sebastian Bach” thành “RIPJSB”.

Nếu code comment của bạn gây ra sự nhầm lẫn thay vì biện minh cho nó, hãy xóa nó đi.

5. Quy tắc 5: Giải thích unidiomatic code trong code comment

Bạn nên viết code comment mà người khác coi là không cần thiết hoặc thừa, chẳng hạn như code dưới đây từ App Inventor:

Nếu không có code comment, người khác có thể đơn giản hóa code hoặc xem nó như một câu lệnh bí ẩn nhưng cần thiết. Hãy viết ra lý do tại sao bạn phải bổ sung thêm code comment để tiết kiệm thời gian suy nghĩ của người đọc.

6. Quy tắc 6: Cung cấp liên kết đến nguồn gốc của code được sao chép

Nhiều lập trình viên sử dụng code có sẵn trên Internet. Trong trường hợp này, bạn nên viết code comment cung cấp một tham chiếu đến nguồn sao chép để người đọc có thể hiểu được ngữ cảnh đầy đủ, chẳng hạn như:

• Vấn đề gì đang được giải quyết?
• Ai đã cung cấp code đó?
• Tại sao giải pháp được đề xuất?
• Những người bình luận nghĩ gì về nó?
• Nó có thể được cải thiện như thế nào?

Ví dụ, hãy xem xét code comment này:

Liên kết được thêm vào câu trả lời cho biết:

• Tác giả của đoạn mã là Tomáš Procházka, người nằm trong top 3% trên Stack Overflow.
• Một người bình luận cung cấp một code tối ưu hóa, đã được tích hợp vào repo.
• Một người bình luận khác gợi ý một cách để tránh những tình huống tranh cãi xảy ra.

Đối chiếu code comment trên với nhận xét này:

Bất kỳ ai muốn hiểu mã này sẽ phải tìm kiếm công thức. Dán URL nhanh hơn nhiều so với việc tìm kiếm tài liệu tham khảo sau đó. 

Một số lập trình viên có thể biện minh rằng họ không tự viết mã, nhưng việc sử dụng lại mã có thể là tiết kiệm thời gian và mang lại nhiều lợi ích hơn. Tất nhiên, lập trình viên không bao giờ nên sao chép code khi họ không hiểu về nó. 

Mọi người sao chép rất nhiều code từ các câu hỏi và câu trả lời trên website của Stack Overflow. Code đó thuộc giấy phép Creative Commons, vì vậy bạn nên viết code comment trích nguồn như sau:

>>> Đọc ngay: Học lập trình online có ưu điểm vượt trội gì?

7. Quy tắc 7: Viết comment chứa các liên kết đến tài liệu tham khảo nếu chúng hữu ích

Tất nhiên, không phải tất cả các tham chiếu đều lấy từ Stack Overflow. Xem xét code comment dưới đây:

Link đến các tài liệu khác có thể giúp người đọc hiểu được vấn đề mà code của bạn đang giải quyết. Mặc dù thông tin này có thể nằm ở đâu đó trong tài liệu tham khảo, nhưng một bình luận được đặt đúng vị trí sẽ cung cấp cho người đọc gợi ý nên đọc nó khi nào và ở đâu. Trong trường hợp này, việc truy cập liên kết chỉ ra rằng RFC 4180 đã được cập nhật bởi RFC 7111 – một thông tin rất hữu ích.

8. Quy tắc 8: Viết code comment khi sửa lỗi

Không chỉ khi viết code bạn mới nên viết code comment mà cả khi sửa lỗi, code comment cũng nên được thêm vào. Hãy xem xét code comment dưới đây:

Comment không chỉ giúp người đọc hiểu code, mà còn hữu ích cho việc xác định xem code có còn cần thiết hay không và làm thế nào để kiểm tra nó. Nó cũng có thể hữu ích khi người đọc tham khảo các hệ thống theo dõi vấn đề:

git blame có thể được sử dụng để tìm kiếm dòng code được thêm vào hoặc sửa đổi. Nó cần được viết một cách ngắn gọn và nêu ra sự thay đổi quan trọng nhất (ví dụ: khắc phục sự cố # 1425, di chuyển một phương thức từ tệp này sang tệp khác).

9. Quy tắc 9: Sử dụng comment để đánh dấu các tác vụ chưa hoàn thành

Đôi khi lập trình viên cần phải kiểm tra code mặc dù đã biết những hạn chế của nó. Thay vì không bình luận về những hạn chế trong code của một người khác, bạn nên làm rõ những điều này, bằng việc viết một TODO comment như sau:

Việc sử dụng định dạng chuẩn cho các nhận xét như vậy sẽ giúp đo lường và giải quyết tác vụ chưa hoàn thành. 

FUNiX hy vọng các ví dụ trên đã cho bạn thấy rằng không nên viết code comment để bào chữa hoặc sửa chữa lỗi cho những bộ code xấu. Tuân theo các quy tắc trên sẽ giúp bạn và team của mình tiết kiệm thời gian và công sức đáng kể. Chúc các bạn thành công!

Bài gốc: https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/

>>> Nếu bạn đang có nhu cầu học lập trình trực tuyến, tìm hiểu ngay tại đây:

>>> Xem thêm bài viết:

7+ bước giúp bạn học lập trình viết code tốt hơn

Học lập trình tại FUNiX không chỉ giúp bạn giỏi code

Những website luyện thuật toán lập trình giúp bạn học code hiệu quả

5 điều có thể bạn chưa biết về học lập trình trực tuyến FUNiX

Review khóa học trực tuyến FUNiX FPT đang được nhiều bạn trẻ lựa chọn

FUNiX đào tạo lập trình trực tuyến cung cấp nhân sự tập đoàn FPT

5 Điểm đáng chú ý tại khóa học lập trình trực tuyến FPT – FUNiX

Phạm Thị Thanh Ngọc (theo Stackoverflow)