Hướng dẫn viết chú thích mã nguồn tốt

• Vai trò của chú thích mã nguồn:

  • Chú thích mã nguồn không chỉ giải thích ‘đoạn mã do mình viết đang làm gì’ mà còn ghi lại các cân nhắc như quyết định thiết kế và các đánh đổi
  • Nhờ đó có thể giải thích ‘người viết mã đã làm gì và vì sao lại làm như vậy’
  • Chú thích mã nguồn giúp chia sẻ bối cảnh của những quyết định đã được đưa ra trong quá trình viết mã trước đây
  • Điều này truyền tải những thông tin về mã mà chỉ riêng mã nguồn khó thể hiện được

• Tầm quan trọng của chú thích mã nguồn:

  • Chú thích nội tuyến đặt trước các đoạn mã phức tạp giúp tiết kiệm thời gian cho các lập trình viên khác khi xem lại mã sau này
  • Dự án càng phát triển thì việc lưu lại bối cảnh của các quyết định mã trong quá khứ càng hữu ích cho những lập trình viên khác
  • Nếu mã phức tạp thì nên có ít nhất một chú thích nội tuyến một dòng ở phía trước
  • Chỉ riêng mã nguồn có giới hạn trong việc truyền tải nhiều thông tin khác nhau, bao gồm cả bối cảnh của các quyết định trong mã

• Cách viết chú thích mã nguồn tốt:

  1. Viết ngắn gọn
     • Chỉ viết chú thích khi thật sự cần thiết và chỉ bao gồm thông tin cốt lõi
       • Khi mã phức tạp là điều không thể tránh khỏi
       • Khi cần thêm chi tiết để tăng độ chính xác
       • Khi thiếu bối cảnh (ví dụ: khi sử dụng mã từ repository hoặc package khác)
     • Giảm sự rối rắm và mơ hồ trong chú thích, đồng thời cung cấp bối cảnh và thông tin hữu ích
  2. Sử dụng chú thích TODOs/FIXMEs
     • Chú thích TODOs/FIXMEs là cách để biểu thị rằng ‘một phần cụ thể của mã vẫn chưa hoàn thành hoặc cần được sửa’
     • Có thể viết theo kiểu như “TODO: cần thêm tính năng XX” ở trước hàm
     • Khi đang viết mã mà nảy ra suy nghĩ như 'phần này cần xem lại sau' hoặc 'tính năng này cần phát triển trong tương lai', có thể dùng cách này để ghi lại và theo dõi các mục liên quan
     • Extension hữu ích nên dùng: TODO Highlight
  3. Đừng biện minh cho mã bằng chú thích
     • Thay vì gắn chú thích để biện minh cho mã sai hoặc khó hiểu, hãy viết lại mã
     • Có những đoạn mã cần được giải thích bằng chú thích, nhưng cũng có những đoạn nên tự ‘lên tiếng’ bằng chính mã nguồn mà không phụ thuộc vào chú thích
  4. Tận dụng AI
     • Dùng trình tạo chú thích bằng AI có thể tạo chú thích theo định dạng nhất quán dựa trên một số tiêu chuẩn nhất định
     • Có thể duy trì tính nhất quán của chú thích trong toàn bộ dự án, từ đó cải thiện khả năng đọc của mã
     • Trình tạo chú thích AI hữu ích nên dùng: Readable

[penza1]

Nếu cảm thấy có vẻ cần chú thích,
thì có lẽ cũng nên thử nghĩ xem có phải bản thân đoạn mã đang có vấn đề hay không.

Những chú thích không cùng sống, cùng thay đổi với mã và chức năng của nó
có thể gây ra sự lẫn lộn cho lập trình viên sẽ đọc chú thích đó trong tương lai, hoặc cho chính bản thân mình.

Dù ngữ cảnh trong quá khứ không còn liên quan đến hiện tại hoặc thậm chí đã gây ra lỗi,
thì chính câu chữ mô tả ngữ cảnh cũ đó lại có thể khiến ta ngần ngại khi sửa ở hiện tại, hoặc phải đi đường vòng để giải quyết theo một cấu trúc khác,
và còn có thể làm phát sinh thêm sai sót nữa...

Theo kinh nghiệm của tôi, không có nhiều chú thích thực sự giúp ta hiểu được vì sao thứ từng đúng khi đó mà giờ lại sai....

[ironlung]

Cảm ơn bạn đã chia sẻ một ý kiến rất quý giá. Khi suy nghĩ về ý kiến bạn đã chia sẻ, tôi thấy rằng để mã nguồn phát triển tốt hơn, cũng cần nỗ lực xem xét thật kỹ xem chú thích có thực sự cần thiết hay không. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Xem cái này xong tôi cũng cố gắng đừng viết chú thích quá nhiều nữa

[ironlung]

Cảm ơn bạn đã chia sẻ một video hay! :)

[iamchanii]

Dù đường sá có được trải nhựa tốt đến đâu, tôi vẫn nghĩ biển chỉ dẫn là thứ nhất định phải có. Vì vậy dạo gần đây tôi đang cố gắng biến việc viết chú thích thành một thói quen.

[ironlung]

Cảm ơn bạn đã chia sẻ góc nhìn trong phần bình luận. Ngẫm lại những gì bạn nói, tôi nhận ra chú thích cũng là một phần quan trọng của technical writing, nên khiến tôi muốn nhìn lại các nguyên tắc cơ bản của việc viết. :)

[balak]

Mình nghĩ tốt nhất là viết code sao cho có thể hiểu được ngay cả khi không có comment.

[ironlung]

Vâng, tôi cũng nghĩ trước hết vẫn nên bám sát những điều cơ bản. Cảm ơn bạn đã bình luận. :)