The Art of Readble Code (Part III)

Knowing What to Comment

V. Sử dụng comment một cách hợp lý

• Mục tiêu của phần này là giúp bạn nhận ra rằng những nơi nào bạn cần đặt comment. Bạn có thể nghĩ mục tiêu của việc comment là giải thích những gì đoạn code làm nhưng thực ra nó chỉ là một phần nhỏ của nó .

• **KEY IDEA : Mục tiêu của việc comment đó chính là giúp cho người đọc hiểu các nhiều càng tốt những thứ người viết đã làm **

• Khi bạn đang viết code, bạn có rất nhiều thông tin có giá trị trong đầu của bạn. Khi người khác đọc code của bạn, những thông đó sẽ bị mất - Tất cả những gì họ có là những đoạn code trước mặt của họ .

• Trong bài này, chúng ta sẽ cho thấy rất nhiều ví dụ của khi nào viết xuống những thông tin trong đầu chúng ta. Chúng ta tách rời những khía cạnh bình thường của việc comment. Thay vào đó đi vào tập trung hơn vào những khía cạnh thú vị

• Bài này được tổ chức theo các mục dưới đây:

  +) Biết được cài gì không để comment

  +) Ghi lại những gì bạn nghĩ như code của bạn

1. Biết được cài gì không để comment (What NOT to Comment)

• Việc đọc comment lấy đi thời gian nhiều hơn so với việc đọc code thật sự, và với mỗi comment lấy đi không gian trên màn hình. Vì vậy đâu là sự khác biệt giữa một comment tốt và một comment không có giá trị.

** - Ví dụ 1: Những comment dưới đây là vô giá trị **

Chúng là những comment vô giá trị bởi vì chúng không cung cấp bất kì thông tin mới nào để giúp người đọc hiểu code tốt hơn.

** KEY IDEA : Không comment sự thật có thể được hiểu một cách nhanh chóng từ chính những đoạn code **

Cụm từ Nhanh chóng ở đấy chính là sự phân biệt quan trọng . Xem xét comment dưới đấy cho đoạn code Python này :

Về kĩ thuât, Comment này không thể hiện bất kì thông tin mới nào. Nếu bạn nhìn vào chính bản thân đoạn code, cuối cùng bạn vẫn sẽ hiểu nó hoạt động thế nào . Những với hầu hết người lập trình việc đọc comment code là nhanh hơn việc hiểu đoạn code mà không có nó .

** - Ví dụ 2 : Không comment chỉ vì lợi ích của việc của các comment **

• Một vài vị giáo sư yêu cầu học sinh của họ phải comment vào mỗi function trong bài tập code về nhà của họ. Và như kết quả, một vài lập trình viên cảm thấy có tội về việc để những function khỏa thân mà không có những comment.

Đây chính là một ví dụ về việc những Comment không có giá trị. Định nghĩa của function và comment là giống nhau. Comment này nên được loại bỏ hoặc cải thiện .

Nếu bạn muốn có một comment ở đây, nó cỏ thể tốt hơn bằng cách bổ sung thêm chi tiết

** - Ví dụ 3: Không comment những tên xấu **

• Một comment không nên làm đẹp hơn cho 1 cái tên xấu . Cho ví dụ, dưới đây là một comment cho function có tên CleanReply():

• Hầu hết các comment thường giải thích "clean" có nghĩa gì, thay vào đó cụm từ "enforce limits"(giới hạn thực thi) nên được đưa vào function name

• Tên của function này là mang nhiều ý nghĩa hơn. Một cái tên hay là tốt hơn so với một comment hay bởi vì no sẽ nhìn thầy ở mọi nơi khi function được sử dụng

• Dưới đây là một ví dụ khác của việc comment cho một cái nên nghèo ý nghĩa

Cái tên DeleteRegistry nghe có vẻ như một function nguy hiểm (?) và comment "This doesn’t modify the actual registry" đang cố gắng để xóa đi sự nhầm lẫn

Thay vào đó ta có thể sử dụng cái tên mang ý nghĩa hay hơn :

** KEY IDEA : good code > bad code + good comments. **

2. Ghi lại những gì bạn nghĩ (Recording Your Thoughts)

Bây giờ bạn đã biết được những cái gì không nên comment và chúng ta hãy thảo luận những cái gì nên được comment.

• Một comment tốt có thể mang ý nghĩ hơn việc "ghi lại những gì bạn nghĩ" - Đó là những ý nghĩ quan trọng bạn có như khi bạn viết code

** - Ví dụ 1 : comment trên hằng số của bạn **

• Khi bạn định nghĩa 1 hằng số, đây là một câu chuyện thường xuyên cho việc bạn xác định hằng số này để làm gì hoặc tại sao nó có một giá trị đặc biệt. Ví dụ nhìn vào một hằng số trên code của bạn :

• Nó có vẻ như dòng trên cần một comment . Nhưng nó có vẻ như là người lập trình chọn nó biết nhiều hơn về nó :

• Bây giờ người đọc code này sẽ có một vài hướng dẫn để điều chỉnh giá trị này nếu cần . Hoặc đôi khi giá trị chính xác của 1 hằng sô là không quan trọng với tất cả. Một comment có hảnh hưởng thì vẫn có ích

• Đôi khi nó là một giá trị mà được điều chỉnh cao và có thể không nên được điều chỉnh nhiều

** - Ví dụ 2: Nên bao gồm những bình luận lớn**

• Những bộ phim thường có những bình luận lớn khi mà những nhà làm phim đưa ra những hiểu biết của họ và kể những câu truyện để giúp bạn hiểu bộ phim đã được làm như thế nào. Thông thường, bạn nên thêm những comment để ghi lại những ý tưởng có giá trị về đoạn code

• Đây là một ví dụ :

Comment này dạy cho người đọc một vài thứ và dừng lại việc lãng phí thời gian của họ

• Đây là một ví dụ khác :

• Nếu không có comment này, người đọc có thể nghĩ đây là một bug và có thể lãng phí thời gian cho việc cố gắng đưa ra các test cases làm nó fail hoặc cố gắng để fix bug
• Một comment cũng có thể giải thích tại sao đoạn code không có hình dạng đẹp

Bạn có thể đọc bài viết trước ở đây : https://viblo.asia/cuongnv_540/posts/1ZnbRl30v2Xo

Tài liệu tham khảo : The Art of Readable Code by Dustin Boswell and Trevor Foucher.