[Học lập trình C++] Chương 1: 1.2 Comments

1.2 comments

Các kiểu comments

Một comment là một dòng (hoặc nhiều dòng) của chữ mà được chèn vào mã nguồn để giải thích những gì code đó đang làm. Trong C++ có hai loại comments.

Kí tự // bắt đầu một dòng comment đơn trong C++, cái mà nói cho trình biên dịch bỏ qua mọi thứ cho đến cuối dòng. Ví dụ:

1	std::cout << "Hello world!" << endl; // Everything from here to the right is ignored.

Thông thường, dòng comment đơn được sử dụng để thực hiện một ghi chú nhanh về một dòng code đơn.

Có những dòng code nằm bên phải của dòng có thể làm cả code và comment khó đọc, thông thường nếu dòng đó dài. Do đó, kí tự // thường được đặt phía trên dòng code.

// cout and endl live in the iostream library

std::cout << "Hello world!" << std::endl;

// this is much easier to read

std::cout << "It is very nice to meet you!" << std::endl;

// don't you think so?

std::cout << "Yeah!" << std::endl;

Kí hiệu /* và */ là một cặp kí tự dùng cho nhiều dòng comment. Mọi thứ trong 2 dấu đó đều được bỏ qua.

1 2 3

/* This is a multi-line comment.    This line will be ignored.    So will this one. */

Bởi vì mọi thứ trong hai kí tự đó được bỏ qua, thình thoảng bạn sẽ thấy lập trình viên làm đẹp những dòng comment như sau:

/* This is a multi-line comment.

* the matching asterisks to the left

* can make this easier to read

*/

Kiểu comment nhiều dòng không hỗ trợ việc lồng vào nhau. Do đó, có thể xảy ra những kết quả không mong đợi nếu bạn không lưu ý.

/* This is a multi-line /* comment */ this is not inside the comment */

// The above comment ends at the first */, not the second */

Nguyên tắc không bao giờ được lồng comment bên trong những comment khác.

Sử dụng comment đúng đắn

Thông thường, những comments nên được sử dụng cho ba thứ. Tại thư viện, chương trình hoặc cấp độ hàm, comment được sử dụng tốt nhất là mô tả thư viện, chương trình, hàm làm gì?. Ví dụ:

// This program calculate the student's final grade based on his test and homework scores.

// This function uses newton's method to approximate the root of a given equation.

// The following lines generate a random item based on rarity, level, and a weight factor.

Tất cả các comment ở trên đều đưa cho người đọc một ý tưởng tốt về những gì chương trình đang cố gắng thực hiện mà không cần xem code thực. Một người khác có thể nhìn sơ qua code có thể hiểu và sử dụng lại được. Điều này thực sự quan trọng khi làm việc trong một team, khi mà tất cả các thành viên đều không quen thuộc với code.

Thứ 2, trong thư viện, chương trình, hoặc hàm được mô tả phía trên, comments có thể được sử dụng để mô tả việc code sẽ thực thi mục tiêu như thế nào.

/* To calculate the final grade, we sum all the weighted midterm and homework scores

    and then divide by the number of scores to assign a percentage.  This percentage is

    used to calculate a letter grade. */

// To generate a random item, we're going to do the following:

// 1) Put all of the items of the desired rarity on a list

// 2) Calculate a probability for each item based on level and weight factor

// 3) Choose a random number

// 4) Figure out which item that random number corresponds to

// 5) Return the appropriate item

Những comment đưa cho người lập trình một ý tưởng về việc code sẽ thực thi mục tiêu như thế nào mà không đi quá sâu vào chi tiết.

Tại cấp độ câu lệnh, những comment nên được sử dụng để mô tả “tại sao” code lại làm việc đó. Một comment tệ là giải thích code đó đang làm gì. Nếu bạn đã từng viết code mà lại đi giải thích code đó đang làm gì thì bạn nên viết lại câu lệnh của bạn, đừng comment nó.

Comment tệ:

// Set sight range to 0

sight = 0;

(đúng rồi, chúng ta đã nhìn thấy rõ ràng việc sight được gán về 0 bằng cách nhìn trực tiếp vào câu lệnh rồi mà!)

Comment tốt:

// The player just drank a potion of blindness and can not see anything

sight = 0;

(Bây giờ chúng ta biết “tại sao” biến sight lại được đặt về zero)

Lập trình viên thường phải thực hiện việc ra quyết định giữa việc giải quyết vấn đề theo một cách, hoặc giải quyết vấn đề đó theo cách khác. Comments là một cách tuyệt vời để nhắc nhở chính bạn (hoặc ai đó) lý do để bạn ra quyết định đó thay vì cái khác.

Comment tốt:

// We decided to use a linked list instead of an array because

// arrays do insertion too slowly.

// We're going to use newton's method to find the root of a number because

// there is no deterministic way to solve these equations.

Cuối cùng, comment nên được viết theo cách mà có ý nghĩa để một ai đó không biết code đang làm gì. Nó thường rơi vào trường hợp là một lập trình viên sẽ nói “Những gì điều này làm là hiển nhiên! Không lý gì tôi sẽ quên nó”. Đoán xem chuyện gì xảy ra? Nó không hiển nhiên, và bạn sẽ dễ dàng quên mất nó. Bạn (hoặc ai đó) sẽ rất biết ơn sau đó bởi viết ra code làm gì, làm như thế nào là tại sao phải làm như thế trong ngôn ngữ của con người. Đọc những dòng riêng lẻ của code thì dễ dàng. Hiểu mục đích gì chúng thực thi thì không.

Tóm tắt:

Ở cấp độ thư viện, chương trình, hàm thì mô tả “what”

Trong thư viện, chương trình, hàm thì mô tả “how”

Tại cấp độ câu lệnh thì một tả “why”.

 Commenting out code

Sự chuyển đổi một hoặc nhiều dòng code sang comment được gọi là commenting out code của bạn. Điều này cung cấp một cách thuận tiện (tạm thời) để loại bỏ những phần từ code của bạn mà đã được biên dịch trước đó.

Để commenting out một dòng code đơn, chỉ đơn giản là đặt // vào đầu của một dòng code nào đó.

Uncommented out:

1 2 3

std::cout << 1;     std::cout << 2;     std::cout << 3;

Commented out:

1 2 3

//    std::cout << 1; //    std::cout << 2; //    std::cout << 3;

or

1 2 3 4 5

/*     std::cout << 1;     std::cout << 2;     std::cout << 3; */

Có một vài lý do mà bạn cần phải làm điều này:

1)    Bạn đang làm việc trên một phần mới của code mà bạn chưa muốn biên dịch, và bạn cần phải chạy chương trình. Trình biên dịch sẽ không để cho bạn chạy nếu có một lỗi biên dịch xảy ra. Commenting out code mà bạn không muốn biên dịch lại sẽ cho phép chương trình biên dịch và bạn có thể chạy nó. Khi mà bạn đã sẵn sàng, bạn có thể uncomment code và tiếp tục làm việc trên nó.

2)    Bạn đã viết code mà code đó biên dịch nhưng không làm việc đúng, và bạn không có thời gian để sửa chúng sau đó. Commenting out đoạn code bị lỗi sẽ chắc chắn đoạn code lỗi sẽ không được thực thi và xảy ra vấn đề cho đến khi bạn có thể sửa nó.

3)    Để tìm kiếm nguồn gốc của một lỗi nào đó. Nếu một chương trình không đáp ứng được kết quả mong muốn (hoặc bị crashing), thì có thể hữu ích trong một số trường hợp để vô hiệu hóa những phần code của bạn để có thể cách ly những phần hoạt động không đúng. Nếu bạn comment out một hoặc nhiều dòng code, và chương trình của bạn bắt đầu làm việc như mong đợi (hoặc ngừng crashing), dựa vào những gì bạn comment lần cuối cùng. Bạn có thể nghiên cứu tại sao những dòng code đó là gây ra vấn đề.

4)    Bạn muốn thay thế một phần của code bởi một phần khác của code. Thay vì xóa luôn code gốc, bạn có thể comment nó và để nó ở đấy để tham khảo cho đến khi bạn chắc chắn rằng code mới của bạn hoạt động đúng. Một khi bạn chắc chắn code mới đã hoạt động, bạn có thể xóa đi những gì đã comment. Nếu bạn không thể làm cho code mới hoạt động, bạn có thể xóa luôn code mới và uncomment code cũ để chuyển trở lại những gì đã có trước đó.

Commenting out code là một việc thông thường khi phát triển phần mềm, vì vậy nhiều IDE cung cấp hỗ trợ cho việc commenting out bằng việc bôi màu cho phần code đó.

Một lưu ý về comment trong những bài hướng dẫn này

Suốt phần còn lại của loạt bài hướng dẫn này. Chúng tôi sẽ sử dụng comment bên trong những ví dụ để minh họa cho hoạt động của một cái gì đó. Người đọc sẽ chú ý rằng những comment kiểu như thế là tồi tệ nhưng hãy nhớ rằng những comment như vậy chỉ phục vụ cho mục đích học tập chứ không phải là những comment tốt trong thực tế.

Nguồn learncpp.com