[Training] Code Tells You How, Comments Tell You Why

Chúng ta thường nhìn thấy rất nhiều dòng code (tên biến, các đoạn logic), các method đều có những dòng comment (//) (/* */)

Vậy ý nghĩa của chúng là gì? Chúng có quan trọng không?

Và làm thế nào để chúng ta có thói quen comment code khi chúng ta làm việc trong dự án?

Chúng ta hãy bắt đầu với chia sẻ dưới đây

Đây là một bài viết khá hay mà tôi đọc được ở https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/ Ngoài ra bạn có thể xem thêm ở http://mikegrouchy.com/blog/2013/03/yes-your-code-does-need-comments.html Hoặc ở đây nữa http://www.cs.utah.edu/~germain/PPS/Topics/commenting.html

Trong 1 bài viết gần đây về vấn đề triết học của code comment, tôi đã lưu ý 1 điều với các bạn rằng * Những comment cần thiết nhiết, có ý nghĩa nhất chính là những cái mà bạn nghĩ rằng không cần thiết * Cho phép tôi được làm sáng tỏ quan điểm này. Mục tiêu đầu tiên của bạn khi code đó là làm sao để nó đơn giản nhất có thể để người khác có thể hiểu chính xác nó mà không cần dựa vào những dòng comment. Và chỉ với những chỗ mà bạn không thể clear được nó thì bạn nên comment.

Điều này sẽ giúp người đọc code của bạn nắm được ý tưởng những dòng code này của bạn. Trong 1 cuốn sách "Structure and Interpretation of Computer Programs" (Cấu trúc và mối tương quan của ngôn ngữ lập trình) xuất bản năm 1985, có lời mở đầu như sau

Phần mềm được viết ra để con người đọc nó, máy tính chỉ là nơi thực thi

Trên trang bìa của 1 quyển luận văn của Knuth năm 1984 về ngôn ngữ lập trình cũng có đề cập:

Để thay đổi tư duy truyền thống về cấu trúc của ngôn ngữ lập trình, chúng ta hãy:

Thay vì tưởng tượng việc hướng dẫn máy tính thực hiện công việc chúng ta mong muốn như thế nào, chúng ta hãy tập trung hơn vào việc giải thích với nhân viên rằng chúng ta muốn máy tính làm gì

Những học viên thực hành được mong đợi có thể thay đổi tư duy của họ, tập trung hơn vào việc cải thiện và đưa ra những style thích hợp nhất. Ví dụ, có một học viên đã chọn tên cho các biến của anh ta một cách cẩn thận, giải thích ý nghĩa của từng biến một. Anh ta mong đợi một ứng dụng có thể đáp ứng được các yêu cầu, và dễ hiểu nhất đối với con người, trong đó có sử dụng lẫn cả các method được đặt tên formal và informal

Nếu bạn viết code mà chú ý đến lập trình viên ( những người sẽ maintain sau này), sau đó mới đến máy tính, bạn có thể tìm ra những cách comment hợp lý nhất. Dưới đây là 1 dẫn chứng chực tế. Đoạn code này thuộc một dự án kín và được sử dụng qua nhiều năm.

float _x = abs(x - deviceInfo->position.x) / scale;
int directionCode;
if (0 < _x & x != deviceInfo->position.x) {
    if (0 > x - deviceInfo->position.x) {
        directionCode = 0x04 /*left*/;
    } else if (0 < x - deviceInfo->position.x) {
        directionCode = 0x02 /*right*/;
    }
}

Tương tự như ở đoạn code phía dưới, code đọc dễ hiểu hơn, với một lỗi được sửa

static const int DIRECTIONCODE_RIGHT = 0x02;
static const int DIRECTIONCODE_LEFT = 0x04;
static const int DIRECTIONCODE_NONE = 0x00;

int oldX = deviceInfo->position.x;
int directionCode = (x > oldX)? DIRECTIONCODE_RIGHT
                  : (x < oldX)? DIRECTIONCODE_LEFT
                  : DIRECTIONCODE_NONE;

Chú ý rằng nhiều comment hơn chưa chắc đã khiến code dễ đọc hiểu hơn. Nó không nằm trong bài viết này. Nếu bạn thêm comment cho đoạn code ở trên - kể cả có muốn hay không - thì cũng chỉ làm cho nó lộn xộn hơn mà thôi. Đôi khi ít comment có thể khiến code bạn dễ hiểu hơn. Thậm chí trong một số trường hợp thì tên biến, hàm có ý nghĩa lại lợi hại hơn việc comment rất nhiều.

Mặc dù có những đoạn code đơn giản, hoặc đơn giản chỉ là bạn chỉnh lý lại thì comment cũng là một điều cần thiết, hãy chỉ ra những hạn chế cần cải thiện (khi bạn refector) hoặc đoạn code của bạn chỉ hoạt động trong một ngữ cảnh cụ thể nào đó thôi.

Không quan trọng đoạn code của bạn dài hay ngắn, đơn giản hay phức tạp, comment code cũng rất quan trọng. Code không bao giờ thay thế được comment và ngược lại. Hãy hỏi Jef Raskin về điều này:

Code không thể giải thích lí do tại sao ứng dụng được viết, lí do cho việc chọn method này hay method khác. Code không thể thảo luận ra các lí do để đưa ra các lựa chọn phù hợp ví dụ:

/* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */
What is perfectly, transparently obvious to one developer may be utterly opaque to another developer who has no context. Consider this bit of commenting advice:
You may very well know that

$string = join(',reverse(split(',$string)));

reverses your string, but how hard is it to insert
# Reverse the string
into your Perl file?

Thực tế thì comment cũng không quá khó. Code chỉ có thể có bạn biết chương trình hoạt động như thế nào, comment có thể bảo bạn tại sao nó hoạt động.

Đừng thay đổi tư duy những đồng nghiệp của bạn ngay lập tực nhé, đây là một quá trình lâu dài không được nóng vội.

Cảm ơn các bạn đã theo dõi