The Art Of Readble Code (Part IV)

Making Comments Precise and Compact

VI. Làm cho comments của bạn trở nên chính xác và nhỏ gọn hơn

• Ở phần trước tôi đã giới thiệu cho các bạn về việc nhận ra cái gì bạn nên đặt comments. Ở bài này là về việc viết comment chính xác và nhỏ gọn như thế nào.

• Nếu bạn đang tiến tới việc viết comments, nó nên viết càng cụ thể, chính xác càng tốt. Nói cách khác, những comments sẽ chiếm dụng 1 khoảng không gian trên màn hình, và tốn thêm thời gian để đọc. Vì vậy comment cần gắn gọn.

• **KEY IDEA: Những comments nên hàm chưa thông tin cao và chiếm dụng ít không gian.

• Phần còn lại của bài này sẽ giới thiệu làm sao để làm được như vậy :

1. Giữ comment nhỏ gọn

Đây là một đoạn code ví dụ về việc định nghĩa kiểu C++

Nhưng thay vì sử dụng 3 dòng comments để định nghĩa ta có thể chỉ sử dụng 1 dòng.

2. Tránh dùng đại từ mơ hồ

• Ví dụ một câu minh họa "who is on first?", đại từ có thể làm cho câu thêm khó hiểu. Sẽ mất thời gian hơn hiểu đại từ ở đây là gì. Và trong một vài trường hợp việc không rõ ràng "it" or "this" chỉ đến là gì trong ví dụ sau :

• Trong comment này "it" có thể chỉ đến data or cache. Bạn có thể chỉ ra bằng việc đọc phần code còn lại.Nhưng nếu mà bạn phải làm vậy, thì ý định của comment để làm gì

• Cách an toàn nhất tránh hiểu lầm đó là điền đầy đủ thông tin cho đại từ được sử dụng nếu có bất kì nguy cơ nào đại từ có thể bị hiểu nhầm. Theo ví dụ trước hay thay "it" bằng "the data"

• Đó là cách dễ dàng nhất để làm, bạn cũng có thể cấu trúc lại câu comment trên làm cho "it" dễ hiểu.

3. Câu từ cẩu thả

• Trong nhiều trường hợp, việc làm cho comments thêm dễ hiểu đồng thời cũng làm cho comments trở nên gắn gọn hơn.

• Đây là một ví dụ về web thu thập thông tin:

• Câu trên có vẻ đã ok, nhưng hay so sánh thử với câu dưới đây:

• Câu trên là đơn giản hơn, nhỏ gọn hơn và có tính hướng dẫn hơn. Nó cũng giải thích ở tầng nghĩa cao hơn là trả về URL không được thu thập - thứ mà commnet đầu tiền không để cập tới .

4. Miêu tả chức năng fuction một cách dễ hiểu

• hãy tưởng tượng bạn vừa viết một function đếm số dòng của một file

• Comment trên là rất không chính xác, có rất nhiều cách để định nghĩa thế nào là 1 "line". Đây là một số trường hợp có thể nghĩ ra :

• Cách thực thi dễ nhất là đếm số kí tự xuống dòng \n. Dưới đây là một cách comment dễ hiểu hơn về cách thực thi của hàm này :

• Comment này không dài hơn comment đầu tiên, nhưng bao gôm nhiều thông tin hữu ích hơn. Nó cho người đọc thấy rằng function này có thể return 0 nếu không có dòng mới nào và nó cũng cho thấy rằng kí tự xuống dòng \r không được tính .

• Ở một ví dụ trong thực tế khác. Ví dụ dưới đây là bạn cần insert một số lượng lớn record mà không biết số lượng cho trước là bao nhiêu. Bạn có thể sử dùng mysql PDO sử dụng placeholder

• ở đây cấu sql sẽ có dạng INSERT INTO test(column_name1, column_name2, column_name3, column_name4) VALUES (value11, value12, value13, value14) (value21, value22, value23, value24)..... Vì để đảm bảo an toàn câu lệnh này sẽ dùng placeholder có dạng INSERT INTO test(column_name1, column_name2, column_name3, column_name4) VALUES (?, ?, ?, ?) (?, ?, ?, ?).... việc dùng comment sẽ giúp người đọc hiểu rõ hơn ý định của người viết code khi tạo ra biến $allPlaceholder

5. Đưa ra ví dụ minh họa những trường hợp tiêu biểu

• Khi cần phải comment, chọn một cách cẩn thận ví dụ input/output có thể có giá trị bằng hàng nghìn từ .

• Ví dụ đây là một function có chức năng remove một phần của 1 chuỗi

• Comment này chưa được chuẩn xác cho lắm vì nó không thể trả lời một số câu hỏi như : +) Tất cả các kí tự của chuỗi substring sẽ bị loại bỏ hay là chỉ là một tập các chữ cái ? +) nếu có một lượng bội số của char ở vào cuối của src

• Trong trường hợp này thay vào đó ta hãy đưa ra 1 ví dụ mẫu :

• Ví dụ trên đã khoe được toàn bộ chức năng của function Strip, Chú ý rằng có thể ví dụ đơn giản hơn lại không có ích, nếu nó không thể trả lời được câu hỏi

• Dưới đây là một ví dụ khác :

• Comment này rất chính xác, nhưng hơi khó để tưởng tượng, đây là một ví dụ về comment chứa ví dụ dễ tưởng tượng hơn.

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