Nghệ thuật viết code đẹp - Phần II: Nên viết comment như thế nào?

Bài viết này là phần 2 trong series Nghệ thuật viết code đẹp, tiếp nối Nghệ thuật viết code đẹp - Phần I: Viết flow điều kiện và vòng lặp dễ hiểu. Phần này được viết với mong muốn chia sẻ về cách xác định xem trường hợp nào chúng ta nên viết comment vào source code cho hiệu quả, tránh thiếu cũng như dư thừa. Có một chút chia sẻ về cách viết comment sao cho nhanh chóng và đỡ gây "ngại" cho lập trình viên nữa. Chúng ta thường nghĩ comment được viết ra là để giải thích cho người đọc biết về hoạt động của code. Nhưng thực ra việc viết comment chỉ nên có 1 mục đích duy nhất là: Key

Truyền đạt ý đồ của người viết code cho người đọc code.

Mỗi khi viết ra một hàm hay một class nào đó chúng ta luôn có nhiều suy nghĩ, nhận định của bản thân với những dòng code mình viết ra. Những suy nghĩ đó sẽ rất có ích cho việc đọc hiểu của người tiếp nối nếu được truyền đạt một cách ngắn gọn, dễ hiểu và đầy đủ. Trong bài biết này chúng ta sẽ lần lượt đi qua 3 mục lớn:

1. Những trường hợp không cần viết comment
2. Ghi lại những suy nghĩ của bản thân khi đang viết code
3. Suy nghĩ ở vị trí của người đọc code để hiểu mình cần comment nội dung gì

Nào chúng ta hãy bắt đầu nhé!

Chúng ta hãy xem xét ví dụ dưới đây:

//Định nghĩa class Account
class Account {
  public:
    // Contructor
    Account();
    // Set giá trị mới cho profit
    void SetProfit(double profit);
};

Như các bạn đã thấy ở trên, những comment đó không hề cung cấp thêm một lượng thông tin mới nào, cũng chẳng giúp người đọc code đọc nhanh hơn. Tóm lại là không có một giá trị gì cả. Key

Không comment vào các nội dung mà chỉ cần đọc code là có thể hiểu ngay được

1. Không comment chỉ để giữ quy tắc

Có những nơi quy định bắt buộc phải viết comment đầy đủ cho mỗi function hay class được viết. Nên có những trường hợp thế này

// Tìm Node có name và depth xác định từ subtree được được vào
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

Comment này hoàn toàn không có giá trị vì chỉ cần đọc tên của function là đã có thể hiểu được nhiệm vụ của nó rồi. Nếu cần phải comment thì chúng ta nên comment những nội dung mang lại giá trị cho người đọc. Ví dụ như

// Nếu depth <= 0 thì chỉ tìm kiếm trong subtree
// Nếu depth == N thì tiến hành tìm kiếm trên subtree và tới tầng dưới nói N tầng
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

2. Hãy sửa nếu tên không diễn đạt đủ ý nghĩa thay vì comment vào chỉ để giải thích

// Giải phóng Registry Handle. Tuy nhiên không thay đổi Registry thực sự
void DeleteRegistry(RegistryKey* key);

Nếu nhìn qua tên thì ai cũng nghĩ ngay rằng DeleteRegistry là hàm phải rất cẩn trọng khi sử dụng vì dùng không cẩn thận có thể xoá mất Registry. Tuy nhiên đọc comment thì thấy nó chẳng gây ảnh hưởng gì lên Registry cả. Thay vì comment vào như thế, chúng ta nên lấy một cái tên đẹp hơn cho function này

void ReleaseRegistryHandle(RegistryKey* key);

1. Comment tổng quan

Với mỗi class hay function phức tạp chúng ta nên viết giới thiệu hay thuyết minh tổng quan cho chúng để người đọc có cái nhìn bao quát và đi nhanh hơn trong quá trình đọc chi tiết. Những vấn đề trong source code cần giải quyết. Ví dụ như:

// Class này quá lớn, cấu trúc phức tạp
// Có lẽ nên tạo subclass và để các xử lý phức tạp ít liên quan ở subclass đó

2. Comment vào những điểm còn khúc mắc và chưa được thực hiện

Về cơ bản những phần này sẽ có kí pháp phần mở đầu phân theo từng mục đích:

1. TODO: Để sau làm
2. FIXME: Hiện tại đang có lỗi
3. HACK: Cách làm chưa được tốt lắm, cần cải tiến
4. XXX: Nguy hiểm, có vấn đề lớn Tuỳ từng tổ chức mà có thể thay đổi kí pháp cho phù hợp, ví dụ như vấn đề lớn cần làm thì viết HOA toàn bộ TODO: , vấn đề nhỏ thì viết thường todo:

3. Comment cho hằng số

Với hằng số, chúng ta nên comment để người đọc hiểu tại sao nên chọn giá trị đó. Khi ấy việc chỉnh sửa sẽ nhanh và dễ dàng hơn rất nhiều Ví dụ

image_quality = 0.72;   //Nếu để là 0.72 thì độ lớn của file sẽ hợp với chất lượng màn hình

Khi đó nếu muốn hiển thị đẹp hơn trên loại màn hình độ phân giải cao hơn người đọc chỉ cần tăng giá trị của image_quality lên là xong.

Phần này thì có vẻ hơi lý thuyết một chút, nhưng vẫn có những key riêng cho nó

1. Dự tính trước các thắc mắc người đọc gặp
2. Thông báo trước các cạm bẫy có thể gặp phải gây hiểu lầm trong quá trình đọc
3. Viết comment tổng quan một cách ngắn gọn nhưng đầy đủ ý nghĩa

Viết viết comment tốt thực ra cũng khó như là viết code tốt vậy. Với người cầu toàn lại càng khó lựa chọn ngôn từ và vị trí đặt comment của mình hơn. Để vượt qua trở ngại ấy chúng ta có một key rất đơn giản: Key

Đầu tiên hãy cứ viết ra suy nghĩ trong đầu của mình trước.

Ví dụ:

// Toi rồi, chỗ này mà gặp phải cái list có nhiều phần tử trùng nhau thì sẽ gặp lỗi lớn!

Chúng ta cùng nhau đi phân tích từ câu từ:

1. Toi rồi: Muốn chú ý tới người đọc
2. chỗ này: Đoạn code này
3. mà gặp phải cái list có nhiều phần tử trùng nhau thì sẽ gặp lỗi lớn: Nghĩa là đoạn code này không xử lý được cho trường hợp list có các phần tử trùng nhau

=> Nội dung sửa sẽ là

// Chú ý: Đoạn code này không xử lý được cho list có các phần tử trùng lặp nhau

Vậy tóm lại 3 bước đơn giản để chúng ta có được một comment tốt một cách nhanh chóng là

1. Viết ra ngay suy nghĩ trong đầu
2. Xem lại câu cú xem cần sửa chữa chỗ nào
3. Tiến hành sửa

Trên đây mình đã giới thiệu với các bạn Phần II của series Nghệ thuật viết code đẹp. Chúc các bạn viết được những comment mà người khác đọc vào thấy mình là người có "tâm"