[Clean code] Source code hoàn hảo thì không có quá nhiều comments?

Thông qua chương 4 cuốn Clean code - Robert C.Martin sẽ phần nào giải đáp câu hỏi trên. Theo tác giả thì một trong những động cơ chính để bổ sung comment là do developer viết code không tốt. Bởi khi code rõ ràng và đủ thông tin thì sẽ không cần bổ sung comment để làm rõ nghĩa. Dưới đây là một số nguyên tắc và quan điểm của tá giả về comment trong code:

1.Always try to explain yourself in code

Thay vì comment hãy cố gắng sao cho đoạn code đó có thể biểu thị ý nghĩa và thông tin của chính nó (make your code self-explanatory). Follow naming conventions và có một logic rõ ràng sẽ giúp code trở nên dễ đọc hơn mà không cần bất cứ comment giải thích nào. Ví dụ:

// Bad: 
// Check if the user is active
if (user.getStatus() == 1) {
    // perform some action
}

// Good: 
if (user.isActive()) {
    // perform some action
}

2. Don't be redundant.

Tránh lãng phí comment nếu code đã biểu đạt đủ ý nghĩa của nó. Hãy để những comment có giá trị, hãy comment khi đoạn code không thể hiện được hết ý nghĩa ẩn sau nó. Ví dụ:

// Bad:
// Set the user's name to John
user.setName("John");

// Good:
user.setName("John"); // Setting a specific user name for testing

3. Don't add obvious noise.

Tránh comment khi code đã biểu thị đủ ý nghĩa. Đôi khi nó không làm code rõ ràng hơn mà có phản tác dụng làm codebase trở nên khó hiểu hơn. Ví dụ:

// Bad:
// Increment the counter by one
counter++;

// Good:
counter++;

4. Don't use closing brace comments.

Comment ở sau những dấu “}” thường là không cần thiết bởi nó có thể làm cấu trúc của đoạn code đó trở khó nhìn và khó đọc hơn. Ví dụ:

// Bad:
if (condition) {
    // some code
} // end if

// Good:
if (condition) {
    // some code
}

5. Don't comment out code. Just remove.

Comment code rất dễ gây hiểu lầm cho những developer khác đọc bởi chúng ta không thể biết lý do những đoạn code này được comment để làm gì: để phát triển tiếp hay để xử lý một phần logic nào đó sau này? Những comment code để quá lâu nên được xóa bỏ. Một số Version control systems như Git có thể giúp chúng ta xem lại mà không cần đến việc comment. Ví dụ:

// Bad:
// if (oldCondition) {
//     doSomethingOld();
// }
if (newCondition) {
    doSomethingNew();
}

// Good:
if (newCondition) {
    doSomethingNew();
}

6. Use as explanation of intent.

Sẽ có những lúc code không thể hiện được hết ẩn ý của nó. Đây chính là lúc nên sử dụng comment để giúp đoạn code rõ nghĩa hơn. Hãy dùng comment để giải thích tại sao bạn lại quyết định xử lý như vậy, sẽ giúp cho devloper khác (hoặc chính bạn sau này :v) hiểu nó. Ví dụ:

// Calculate the monthly payment based on the fixed interest rate.
double monthlyPayment = calculateMonthlyPayment(principal, interestRate, term);

7. Use as clarification of code.

Nếu đoạn code chứa những công thức phức tạp hay những thuật toán không phổ biến. Hãy comment để mô tả nó hoạt động như thế nào hay nó dựa trên cơ sở nào. Ví dụ:

// Convert the temperature from Celsius to Fahrenheit
double temperatureInFahrenheit = (temperatureInCelsius * 9/5) + 32;

8. Use as warning of consequences.

Sử dụng comment để cảnh báo hoặc nhắc nhở với những đoạn code tiềm ẩn lỗi hoặc có side effect. Điều này là tốt bởi comment sẽ giúp developers khác tránh lỗi có thể gặp phải và cẩn thận hơn trong quá trình bảo trì và phát triển tiếp codebase. Ví dụ:

// Warning: This method is not thread-safe
public void updateSharedResource() {
    // code to update shared resource
}

Rồi, theo những ý chính của tác giả mình tóm tắt được, có thể trả lời cho câu hỏi ở đầu bài rằng một source code tốt và rõ ràng đúng là sẽ không cần quá nhiều comment. Comment giống như một con dao hai lưỡi sẽ thật hữu ích bởi nó giúp code của bạn trở nên clean hơn khi được đặt đúng chỗ và sẽ thật tệ khi lạm dụng comment ở mọi nơi gây confuse và làm source code trở nên khó bảo trì hơn. Hãy để mỗi byte trong source code đều có ý nghĩa và giá trị!

Mục lục