Bạn thích nhận xét của mình như thế nào?

Question

Thực tiễn tốt nhất của bạn cho nhận xét là gì? Khi nào chúng nên được sử dụng và chúng nên chứa những gì? Hoặc là bình luận ngay cả cần thiết?

Answer 1

Nhận xét là điều cần thiết để bảo trì. Điểm quan trọng nhất cần nhớ là giải thích TẠI SAO bạn đang làm điều gì đó, không phải GÌ bạn đang làm.

Answer 2

Tôi nghĩ điều đó phụ thuộc vào kịch bản.

Phương thức/chức năng/lớp học cần mô tả ngắn gọn về những gì họ làm, cách họ thực hiện, những gì họ thực hiện và những gì họ quay lại, nếu không rõ ràng ngay lập tức và thường (trong mã của tôi) có dạng javadoc khối nhận xét kiểu.

Mã trong khối, tôi có xu hướng để lại nhận xét phía trên một khối dòng để giải thích ý nghĩa của nó hoặc một dòng ở cuối dòng nếu đó là cuộc gọi hàm ngắn và khó hiểu.

Answer 3

Ở trường, quy tắc là để nhận xét mọi thứ, rất nhiều để nhận xét vượt quá mã. Tôi nghĩ rằng đó là ngớ ngẩn.

Tôi nghĩ rằng các bình luận nên được sử dụng để ghi lại "lý do" đằng sau mã, không phải là "làm thế nào" ... chính mã giải thích "cách". Nếu có một hoạt động mà không thực sự rõ ràng là tại sao nó được thực hiện, đó là một nơi tốt cho một bình luận.

TODO và FIXME đôi khi được đưa vào nhận xét, nhưng lý tưởng là chúng nên đi vào công cụ quản lý mã nguồn và theo dõi lỗi của bạn.

Một ngoại lệ mà tôi không để ý là các trình tạo tài liệu sẽ chỉ in tài liệu cho các hàm được nhận xét - trong trường hợp đó, mọi giao diện API và lớp công khai cần được nhận xét ít nhất là đủ để có được tài liệu được tạo.

Answer 4

Sử dụng các từ khóa tìm kiếm và bạn sẽ tìm SO có một đống thảo luận về ý kiến ​​mã đã:

https://stackoverflow.com/questions/tagged/comments

Commenting code

Answer 5

Lý tưởng nhất là chương trình của bạn có thể giao tiếp với người đọc trong mã và không trong nhận xét. Khả năng viết phần mềm mà các lập trình viên khác có thể nhanh chóng hiểu được cách ly các lập trình viên giỏi nhất từ ​​trung bình theo ý kiến ​​của tôi. Thông thường, nếu bạn hoặc đồng nghiệp của bạn không thể hiểu một phần mã mà không có nhận xét, thì đây là một "mã ngửi" và việc tái cấu trúc phải theo thứ tự. Tuy nhiên, sẽ có một số thư viện cổ hoặc tích hợp khác mà một vài ý kiến ​​để hướng dẫn các nhà phát triển trung bình không nhất thiết là xấu.

Answer 6

Thường thì câu trả lời là: nó phụ thuộc. Tôi nghĩ lý do bạn viết bình luận là rất quan trọng đối với quyết định, nếu bình luận là tốt hay xấu. Có nhiều lý do có thể cho ý kiến:

• để làm cho cấu trúc rõ ràng hơn (ví dụ mà vòng lặp kết thúc ở đây)

Xấu: này trông giống như một mùi code càng tốt. Tại sao mã quá phức tạp đến nỗi nó cần một bình luận để xóa nó?

• để giải thích, những gì các mã không

Rất xấu: Đây là theo ý kiến ​​của tôi nguy hiểm. Thường thì điều đó sẽ xảy ra, sau đó bạn thay đổi mã và quên đi nhận xét. Bây giờ bình luận là sai. Thật tồi tệ.

• để chỉ một workaround/A bugfix

Tốt: Đôi khi một giải pháp cho một vấn đề có vẻ rõ ràng, nhưng cách tiếp cận đơn giản có một vấn đề. Nếu bạn khắc phục sự cố, có thể hữu ích khi thêm nhận xét, tại sao phương pháp này được chọn. Nếu không thì một lập trình viên khác sau đó có thể nghĩ, rằng anh ta 'tối ưu hóa' mã và giới thiệu lại lỗi. Hãy nghĩ về vấn đề OpenSSL Debian. Các nhà phát triển Debian đã xóa một biến được đơn vị hóa. Thông thường một biến đơn vị là một vấn đề, trong trường hợp này nó là cần thiết cho sự ngẫu nhiên. Một bình luận mã sẽ giúp làm rõ điều đó.

• cho tài liệu-mục đích

Tốt: Một số tài liệu có thể được tạo ra từ ý kiến ​​định dạng đặc biệt (ví dụ: Javadoc). Nó là hữu ích để tài liệu các API công cộng, đó là một-phải có. Điều quan trọng là phải nhớ, tài liệu đó chứa ý định của mã, không phải là việc triển khai. Vì vậy, trả lời các bình luận câu hỏi 'Tại sao bạn cần phương pháp (và làm thế nào để bạn sử dụng nó)' hoặc phương pháp gì?

Answer 7

Tôi nghĩ rằng phong trào mới để loại bỏ ý kiến ​​là xấu ... lý do, có rất nhiều lập trình viên nghĩ rằng họ đang viết dễ hiểu mã mà không cần ý kiến. Nhưng trong thực tế nó không phải là trường hợp.

Tỷ lệ phần trăm mã người khác bạn đọc và hiểu ngay lập tức .. Có lẽ tôi đọc quá nhiều cổ điển asp, Perl và C++ nhưng hầu hết những thứ tôi đọc đều khó đọc.

Bạn đã bao giờ đọc mã của ai đó chưa và hoàn toàn bị nhầm lẫn bởi mã đó. Bạn có nghĩ rằng họ nghĩ trong khi họ đang viết, điều này là crap nhưng tôi không thực sự quan tâm. Họ có thể nghĩ ohh ... điều này rất thông minh và nó sẽ là SUPER nhanh.

Answer 8

Hãy xem Code Complete. Nó chỉ đơn giản là tốt nhất cho các chủ đề như vậy.

Answer 9

Chỉ cần một số nhận xét:

Nhận xét rất quan trọng đối với mọi thứ không thể dễ dàng suy ra từ mã (ví dụ: thuật toán toán học phức tạp).

Các vấn đề với nhận xét là, chúng cần được duy trì như mã nhưng thường không được duy trì.

tôi không thích bình luận như thế này:

// Create the "Analyze" button 
Button analyzeButton = new Button(); 
analyzeButton.Text = "Analyze"; 
analyzeButton.Location = new Point(100, 100); 
Controls.Add(analyzeButton); 

tốt hơn:

CreateAnalyzeButton(); 


void CreateAnalyzeButton() 
{ 
    Button analyzeButton = new Button(); 
    analyzeButton.Text = "Analyze"; 
    analyzeButton.Location = new Point(100, 100); 
    Controls.Add(analyzeButton); 
} 

Bây giờ các mã kể toàn bộ câu chuyện. Không cần bình luận.