Trường hợp sử dụng tốt các nhận xét

Question

Tôi luôn ghét những bình luận chỉ lấp đầy nửa màn hình với dấu hoa thị để cho bạn biết rằng hàm trả về một chuỗi, tôi chưa bao giờ đọc những nhận xét đó.

Tuy nhiên, tôi đọc nhận xét mô tả lý do tại sao một số điều được thực hiện và cách nó được thực hiện (thường là các nhận xét dòng đơn trong mã); những thứ này thực sự tiện dụng khi cố gắng hiểu mã của người khác. Nhưng khi nói đến việc viết bình luận, tôi không viết nó, thay vào đó, tôi chỉ sử dụng bình luận khi viết các thuật toán trong các cuộc thi lập trình, tôi sẽ nghĩ cách thuật toán sẽ làm những gì nó làm sau đó tôi sẽ viết mỗi người trong một nhận xét, sau đó viết mã tương ứng với nhận xét đó.

Một ví dụ sẽ là:

//loop though all the names from n to j - 1 

Khác hơn là tôi không thể tưởng tượng tại sao mọi người sẽ lãng phí thời gian quý báu viết bình luận khi ông có thể được viết mã.

Tôi có đúng hay sai? Tui bỏ lỡ điều gì vậy? Tôi không nhận thức được trường hợp sử dụng tốt nào khác của các nhận xét?

Answer 1

Nếu bạn sử dụng một cái gì đó như Doxygen, bạn có thể ghi lại đầy đủ các loại trả lại, đối số, v.v. và tạo một "hướng dẫn sử dụng mã nguồn" tốt đẹp. Tôi thường làm điều này cho khách hàng để nhóm kế thừa mã của tôi không bị mất hoàn toàn (hoặc buộc phải xem lại mọi tiêu đề).

Các khối tài liệu thường quá hạn, đặc biệt là các ngôn ngữ được nhập mạnh. Nó có ý nghĩa hơn rất nhiều để được tiết lộ với một cái gì đó như Python hay PHP hơn C++ hoặc Java. Điều đó nói rằng, nó vẫn còn tốt đẹp để làm cho các phương pháp & thành viên mà không phải là tự giải thích (không được đặt tên cập nhật, ví dụ).

Tôi đã được lưu nhiều giờ suy nghĩ, chỉ đơn giản bằng cách bình luận những gì tôi muốn nói với bản thân mình nếu tôi đọc mã của tôi lần đầu tiên. Nhiều câu chuyện và ít quan sát hơn. Nhận xét không chỉ giúp ích cho người khác, mà còn tự mình cũng chính là ... ... đặc biệt là nếu bạn chưa chạm vào nó trong năm năm. Tôi có một số Perl mười tuổi mà tôi đã viết và tôi vẫn không biết nó làm gì nữa.

Điều gì đó rất bẩn, mà tôi đã thực hiện trong PHP & Python, là sử dụng sự phản chiếu để truy xuất các khối nhận xét và các yếu tố nhãn trong giao diện người dùng. Đó là một trường hợp sử dụng, mặc dù khó chịu.

Nếu sử dụng trình theo dõi lỗi, tôi cũng sẽ thả ID lỗi gần các thay đổi của mình, để tôi có tham chiếu về trình theo dõi. Điều này là ngoài mô tả ngắn gọn về thay đổi (bản ghi thay đổi nội tuyến).

Tôi cũng vi phạm quy tắc "chỉ bình luận tại sao không phải là" khi tôi làm điều gì đó mà đồng nghiệp của tôi hiếm khi thấy ... hoặc khi sự tinh tế là quan trọng. Ví dụ:

for (int i = 50; i--;) cout << i; // looping from 49..0 in reverse 
for (int i = 50; --i;) cout << i; // looping from 49..1 in reverse 

Answer 2

Comments nên bày tỏ tại sao bạn đang làm một cái gì đó không phải những gì bạn đang làm

Answer 3

Đó là một câu ngạn ngữ cũ, nhưng một thước đo tốt để sử dụng là:

Comment tại sao bạn đang làm một cái gì đó, không phải là cách bạn đang làm việc đó.

Nói "lặp qua tất cả các tên từ n đến j-1" phải được xóa ngay lập tức ngay cả lập trình viên mới làm quen với mã. Đưa ra lý do tại sao bạn làm điều đó có thể giúp dễ đọc.

Answer 4

Nó không phải là một ý tưởng tồi để ghi lại những gì bạn nghĩ mã của bạn nên đạt được (đặc biệt là nếu mã là không trực quan, nếu bạn muốn giữ ý kiến ​​xuống mức tối thiểu) để người đọc nó một ngày sau đó, có một thời gian dễ dàng hơn khi gỡ lỗi/sửa lỗi. Mặc dù một trong những điều khó chịu nhất khi đọc mã của người khác là trường hợp mã đã được cập nhật, nhưng không phải là nhận xét ....

Answer 5

Tôi luôn ghét ý kiến ​​mà điền vào một nửa màn hình với dấu hoa thị chỉ để cho bạn biết rằng hàm trả về một chuỗi, tôi không bao giờ đọc những bình luận.

Một số ý kiến ​​trong tĩnh mạch đó, không phải thường với định dạng rằng cực đoan, thực sự tồn tại để giúp các công cụ như JavaDoc và Doxygen tạo tài liệu cho mã của bạn. Điều này, tôi nghĩ, là một dạng nhận xét tốt, bởi vì nó có cả định dạng có thể đọc được bằng máy tính và người dùng (vì vậy máy có thể dịch nó sang các định dạng khác, hữu ích hơn như HTML), đặt tài liệu gần mã rằng tài liệu đó (để nếu mã thay đổi, tài liệu có nhiều khả năng được cập nhật để phản ánh những thay đổi này), và thường đưa ra lời giải thích tốt (và ngay lập tức) cho người mới vào một codebase lớn tại sao một hàm cụ thể tồn tại.

Nếu không, tôi đồng ý với mọi thứ khác đã được nêu. Bình luận tại sao, và chỉ bình luận khi nó không rõ ràng. Khác với nhận xét của Doxygen, mã của tôi thường có rất ít nhận xét.

Answer 6

Nhận xét mọi thứ bạn nghĩ không đơn giản và bạn sẽ không thể hiểu được lần sau bạn xem mã của bạn.

Answer 7

Một loại bình luận, nói chung là vô dụng là:

// Commented out by Lumpy Cheetosian on 1/17/2009 

... uh, OK, hệ thống kiểm soát nguồn sẽ nói với tôi rằng. Những gì nó sẽ không cho tôi biết là tại sao Lumpy nhận xét ra đoạn mã dường như cần thiết này. Vì Lumpy nằm ở Elbonia, tôi sẽ không thể tìm ra cho đến thứ Hai khi tất cả họ trở về từ lễ hội nghỉ lễ Snerkrumph.

Cân nhắc đối tượng của bạn và giảm mức độ tiếng ồn. Nếu nhận xét của bạn bao gồm quá nhiều crap không liên quan, các nhà phát triển sẽ chỉ bỏ qua chúng trong thực tế.

BTW: (. Hoặc Doxygen, hoặc equiv) Javadoc là một điều tốt (tm), IMHO.

Answer 8

Tôi cũng sử dụng nhận xét để ghi lại yêu cầu cụ thể đến từ đâu. Bằng cách đó, nhà phát triển sau này có thể xem xét yêu cầu đã khiến mã giống như yêu cầu và, nếu yêu cầu mới mâu thuẫn với yêu cầu khác, hãy giải quyết trước khi phá vỡ quy trình hiện có. Nơi tôi làm việc mọi yêu cầu thường có thể đến từ các nhóm người khác nhau có thể không nhận thức được các yêu cầu khác thì hệ thống phải đáp ứng. Chúng tôi cũng thường xuyên được hỏi lý do tại sao chúng tôi đang làm một điều nhất định cho một khách hàng cụ thể và nó giúp để có thể nghiên cứu để biết những yêu cầu trong hệ thống theo dõi của chúng tôi đã làm cho mã như thế nào. Điều này cũng có thể được thực hiện khi lưu mã trong hệ thống contol nguồn, nhưng tôi cũng xem xét các ghi chú đó là nhận xét.

Answer 9

tôi sử dụng ý kiến ​​trong các tình huống sau đây:

1. -mức cao bình luận tài liệu API, ví dụ: lớp này hay chức năng là để làm gì?
2. Nhận xét "lý do".
3. Tóm tắt ngắn, cấp cao về khối mã dài hơn nhiều. Từ khóa ở đây là tóm tắt. Nếu ai đó muốn biết thêm chi tiết, mã phải đủ rõ ràng để họ có thể lấy mã từ mã. Vấn đề ở đây là làm cho nó dễ dàng cho một người nào đó duyệt mã để tìm ra nơi mà một số phần của logic mà không cần phải lội qua các chi tiết về cách nó được thực hiện. Lý tưởng nhất là những trường hợp này nên được tính ra thành các hàm riêng biệt thay vào đó, nhưng đôi khi nó không thể thực hiện được vì hàm sẽ có 15 tham số và/hoặc không được đặt tên.
4. Chỉ ra sự tinh tế có thể nhìn thấy được từ việc đọc mã nếu bạn thực sự chú ý, nhưng không nổi bật nhiều như chúng nên cho tầm quan trọng của chúng.
5. Khi tôi có lý do chính đáng tại sao tôi cần để làm điều gì đó theo cách hack (hiệu suất, v.v.) và không thể viết mã rõ ràng hơn thay vì sử dụng nhận xét.

Answer 10

Nhắc tôi

Real programmers don't write documentation

Answer 11

tôi đã viết nhận xét này một thời gian trước đây, và nó đã cứu tôi giờ kể từ:

// NOTE: the close-bracket above is NOT the class Items. 
// There are multiple classes in this file. 
// I've already wasted lots of time wondering, 
// "why does this new method I added at the end of the class not exist?".