Liệu Bạn Đã Biết Comment Code?

Liệu Bạn Đã Biết Comment Code?

Comment code luôn là một trong những bài học đầu tiên khi bạn tiếp xúc với ngôn ngữ lập trình. Ấy thế, comment cũng cần phải có “nghệ thuật” và không phải ai cũng biết tận dụng sức mạnh của comment đâu nhé! 

Trước khi bắt đầu phần chia sẻ, mình tạm chia comment ra làm hai “trường phái” đó là Bad commentGood comment. Rõ ràng là coder nào cũng muốn theo đuổi Good comment. Nhưng có một sự thật là, muốn tạo ra cái đẹp thì chúng ta phải nhận dạng được thế nào là xấu cái đã!

1. Bad comment nhìn như thế nào?

Comment code gây lãng phí thời gian vô ích

Đây chính là những comment giải thích dòng code đó làm gì. Ví dụ như:

const int size = 10;
// Gán smallestIndex bằng 0
int smallestIndex = 0;
for (int startIndex = smallestIndex + 1; startIndex < size; ++startIndex)
{
    //...
}

Nhìn vào dòng code ai cũng hiểu smallestIndex được gán bằng 0, nhưng tại sao?

Hay:

int array[] = { 1, 59, 33, 66 };
// Sử dụng insertion sort sắp xếp mảng
InsertionSort(array);

Nhìn vào comment này ai cũng hiểu sắp xếp mảng bằng insertion sort, nhưng tại sao?

Qua 2 ví dụ trên, chắc các bạn cũng có thể nhận ra rằng, nếu có những dòng comment, người đọc sẽ mất thời gian để đọc và hiểu. Nhưng nếu đọc xong comment mà không có một tác dụng nào khác do những dòng code đã quá rõ ràng và đôi khi là nhìn code còn hiểu nhanh hơn thì chúng ta nên xem xét lại sự hiện diện của chúng! (một sự lãng phí thời gian vô ích của người viết và người đọc)

Tránh dùng comment để “lấp liếm” vấn đề

Đôi khi, nhũng người lập trình dùng comment để trở nên "lười biếng" hơn. Họ sử dụng những dòng comment thay vì viết code có ý nghĩa hơn. Và đây là một tình huống như vậy:

// Thu hồi bộ nhớ cho key
// không thu hồi registry trong database.
void DeleteRegistry(RegistryKey* key);

Nếu như bạn nào từng lập trình qua C++ thì chắc sẽ biết tới khái niệm con trỏ, trong C++ không có cơ chế giải phóng bộ nhớ tự động như các ngôn ngữ lập trình cấp cao khác, khi không dùng nữa chúng ta cần phải tự delete con trỏ đi để không gây nên vùng nhớ rác.

Ở đây, người lập trình đơn giản chỉ muốn giải phóng vùng nhớ mà con trỏ đang nắm giữ, thế nhưng cách đặt tên hàm thực sự có vấn đề: nó khiến người ta hiểu lầm chức năng của hàm này là xoá 1 Registry ở trong database đi. Để tránh hiểu lầm thì người viết comment một dòng ý nghĩa thực sự cho nó. Việc dùng comment để lấp liếm vấn đề có thể gây thảm hoạ nếu người kế thừa không thực sự hiểu rõ ý nghĩa của nó.

Trong trường hợp này, tốt hơn là chúng ta cần tuân thủ coding convention, naming convention để dòng code trở nên dễ hiểu hơn:

void ReleaseRegistryHandle(RegistryKey* key);

Một điểm lưu ý, có thể bạn đang viết một đoạn code rất phức tạp, và cần một comment để giải thích cho đoạn code đó. Nhưng hãy dừng lại và suy nghĩ xem có thể sửa lại đoạn code của bạn sao cho dễ hiểu hơn được không?

    Ngoài ra, các bạn cũng nên chú ý đến việc “comment rác”, tức là ý nghĩa comment một đàng mà code xử lí một kiểu. Khi sửa chức năng của một đoạn code nào đó, hãy đảm bảo là những dòng comment cũng được kiểm tra lại tương ứng.

    2. Làm sao để có Good comment

    Giờ thì chúng ta sẽ cùng nhau bàn luận thế nào là Good comment nhé.

    Ở mức library, program hoặc function

    Một good comment sẽ mô tả được library, program hoặc function đó có nhiệm vụ gì:

    //************************************
    // Description: Chương trình tính thời gian xây được nhà dựa vào nơi bạn sống và ngành nghề của bạn
    //************************************
    double TinhThoiGianXayNha(string address, string job)

    Những comment như trên sẽ giúp người khác nhanh chóng hiểu được một library, program hoặc function đó có mục đích gì, mà không cần phải nhìn vào những đoạn code của nó. Thông thường, những comment ở mức library có thể nằm trong file readme.txt, hoặc trên main function đối với một program.

    Bên trong library, program hoặc function

    Một good comment sẽ mô tả được library, program hoặc function đó thực hiện như thế nào:

    double TinhThoiGianXayNha(string address, string job)
    {
    //************************************
    // Để tính được thời gian bạn có thể xây nhà, chương trình sẽ :
    // 1. Thống kê mức lương trung bình ngành nghề của bạn
    // 2. Tính chi phí sinh hoạt trung bình nơi bạn đang sống
    // 3. Tính thêm tỉ lệ lạm phát nơi bạn sống,
    // ...
    // Lấy kết quả nhân 69 sẽ ra.
    //************************************
    // code here...
    return 0;
    }

    Những comment như trên sẽ cho người khác biết ý tưởng thực hiện cơ bản của library, program hoặc một function, mà không cần phải xem đến từng dòng code. Có một luu ý nhỏ là những comment ở mức này không cần giải thích quá chi tiết.

    Ở mức từng dòng code

    Một good comment sẽ giải thích tại sao.

    // smallestIndex1 là chỉ số của phần tử nhỏ nhất, giả sử phần tử đầu tiên
    int smallestIndex1 = 0;
    for (int startIndex = smallestIndex1 + 1; startIndex < size; ++startIndex)
    {
    //...
    }

    Hoặc:

    int array[] = { 1, 59, 33, 66 };
    // Cần một thuật toán ổn định, hiệu suất không thực sự quan trọng
    InsertionSort(array);

    Ngoài ra, trong trường hợp không thể đơn giản được code thì bạn nên comment những dòng code phức tạp kiểu thế này.

    //xóa mọi thứ sau kí tự '*' thứ hai
    name = '*'.join(line.split('*')[:2]);

    Mặc dù chúng ta vẫn có thể hiểu được ý nghĩa của những dòng code trên, tuy nhiên sẽ nhanh hơn rất nhiều nếu chúng ta nhận ra ngay được ý tưởng qua việc đọc comment

    3. Vị trí đặt comment

    Đa số các ngôn ngữ lập trình đều có hai dạng comment đó là comment một dòng và comment nhiều dòng. Và vị trí đặt comment ở đâu cũng là một vấn đề mình muốn đề cập đến.

    Đối với comment một dòng

    Khi sử dụng comment dòng, bạn không nên đặt comment bên phải dòng code vì nó sẽ gây khó đọc cho cả code và comment của bạn, đặc biệt đối với những dòng code dài. 

    cout << "Hello World!" << endl;  // Comment để giải thích cho dòng này

    Vì vậy, comment // thường được đặt phía trên của dòng code cần giải thích

    // Comment để giải thích cho dòng này
    cout << "Hello World!" << endl;

    Đối với commet nhiều dòng

    Comment nhiều dòng thường được sử dụng ở mức library, program hoặc function và ở bên trong library, program hoặc function.

    Bạn hoàn toàn có thể comment giữa dòng code. Ví dụ:

    return /* Đây là comment cho hàm này 
    * và nó là comment nhiều dòng */ 0;

    Do không gây ra lỗi nhưng cách comment này không được khuyến khích. Vì nó làm gián đoạn dòng code của bạn. Tiếp nữa, vị trí đặt của comment dòng nên để ở đầu của file code, đầu hàm, hoặc phía trên bên trong hàm. Do tại các vị trí này, người đọc code sẽ nhìn thấy comment trước khi thấy phần code và dễ dàng nắm bắt được tư tưởng của đoạn code phía sau đó.

    4. Kết luận                                                    

    • Ở mức library, program hoặc function, một good comment sẽ mô tả được library, program hoặc function đó có nhiệm vụ gì
    • Bên trong library, program hoặc function, một good comment sẽ mô tả được library, program hoặc function đó thực hiện như thế nào
    • Ở mức từng dòng code, một good comment sẽ giải thích tại sao. Một bad comment sẽ giải thích dòng code đó làm gì.

    Hãy nhớ câu thần chú: Code tells you HOW, Comments tell you WHY

    Link tham khảo: https://itnext.io/what-makes-a-good-code-comment-5267debd2c24