Clean Code #6: Tại sao và cách viết comment hiệu quả trong lập trình (P1)

1. Tại sao cần viết comment rõ ràng trong lập trình

Việc viết comment có vai trò quan trọng trong bất kỳ dự án lập trình nào. Tuy nhiên, sự phụ thuộc quá mức vào comment có thể dẫn đến tình trạng gọi là Code Smell. Comment nên được xem như giải pháp cuối cùng sau khi đã xem xét các phương án khác để cải thiện độ rõ ràng của code. Mỗi comment cần phải có lý do rõ ràng để tồn tại. Nếu không, chúng chỉ làm tăng tỉ lệ 'signal to noise'.

Nhiều lập trình viên tin rằng code của họ đã đủ rõ ràng mà không cần comment, nhưng trên thực tế, việc truyền đạt ý định một cách rõ ràng không phải là điều dễ dàng.

Câu hỏi cốt lõi cần giải đáp: "Comment có thực sự tốt không, hay chỉ là Code Smell?"

2. Comment như một công cụ cần thiết

Comment không chỉ là một phần cần thiết mà còn là chỗ dựa cho người lập trình. Sau đây là một số quy tắc giúp định hướng cho việc sử dụng comment hiệu quả:

a. Ưu tiên code rõ ràng hơn là comment

Comment có thể rất hữu ích, nhưng nếu code có thể diễn đạt một ý nghĩa tương đương một cách rõ ràng, thì hãy để code tự nói lên điều đó. Code sẽ dễ dàng được bảo trì và là tài liệu tham khảo chính xác cho những gì nó thực hiện.

b. Chỉ sử dụng comment khi code không đủ ý nghĩa

Comment chỉ nên sử dụng khi code không thể tự truyền tải ý nghĩa cần thiết. Dưới đây là danh sách các loại comment cần tránh:

Chúng ta hãy cùng đi sâu vào từng loại comment này.

3. Comment dư thừa (Redundant Comments)

Các comment dư thừa chỉ đơn giản là những gì mà code đã thể hiện. Chúng không mang lại giá trị gia tăng nào và chỉ làm loãng thông tin cần thiết. Ví dụ:

int i = 1; // gán i = 1

var passenger = new Passenger(); // Tạo một hành khách mới

/// <summary>
/// Constructor mặc định
/// </summary>
class Passenger() {
   //
}

/// <summary>
/// Tính tổng chi phí
/// </summary>
class CalculatesTotalCharges() {
   // Tổng chi phí được tính ở đây
}

Sự tồn tại của Redundant Comments phá vỡ nguyên tắc DRY (Don't Repeat Yourself). Chúng ta không nên lặp lại thông tin mà code đã truyền tải.

4. Comment ý định (Intent Comments)

Comment ý định thường được sử dụng để giải thích giá trị của một biến hoặc hằng số, điều này có thể giải quyết dễ dàng bằng cách sử dụng biến có tên rõ ràng hoặc sử dụng enum.

Ví dụ dirty:

// Đảm bảo tài khoản của người dùng đã bị hủy
if(user.Status == 3)

Ví dụ clean:

if(user.Status == Status.InActive) {
   //
}

5. Comment xin lỗi (Apology Comments)

Các comment xin lỗi thường thể hiện tâm lý không chịu trách nhiệm trong việc viết code.

Ví dụ dirty:

// Xin lỗi, đây là một khu vực chưa được hoàn thiện. Tôi chỉ xử lý ngoại lệ mà không đi sâu vào chi tiết.

Lời khuyên

Thay vì để lại comment xin lỗi, hãy khắc phục vấn đề trước khi gửi code. Nếu không thể, hãy thêm comment TODO để đánh dấu công việc còn phải làm.

6. Comment cảnh báo (Warning Comments)

Comment cảnh báo thường biểu thị rằng một phần code nào đó có thể gây ra rắc rối. Tuy nhiên, nếu quá nhiều, chúng có thể trở thành dấu hiệu cho thấy cần tái cấu trúc lại code.

Ví dụ dirty:

// Đây là nơi có lỗi - Liên hệ với Robert để biết thêm chi tiết

Cảm ơn bạn đã theo dõi bài viết này! 🚀 Phần tiếp theo sẽ được tiếp tục trong "Clean Code #6: Viết comment (P2)" để khám phá thêm nhiều chủ đề thú vị hơn trong việc viết comment trong lập trình.
source: viblo