Khi nào là các nhận xét "quá nhiều" và khi nào chúng không đủ?

Question

Có một cuộc tranh luận nhỏ đang diễn ra nơi tôi làm việc về hiệu quả của các nhận xét trong mã. Một trong những khách hàng tiềm năng đã hướng dẫn các nhà phát triển của mình không sử dụng nhận xét vì chúng quá "lỗi thời" và một vài nhà phát triển khác đã chỉ ra rằng họ không bao giờ sử dụng nhận xét vì họ cảm thấy tất cả những gì họ làm là làm lộn xộn mã.

Tôi luôn chú ý đến thực tế rằng tôi nhận xét đầu mỗi tập tin bằng khối nhận xét cơ bản, nhận xét từng định nghĩa phương thức/lớp/v.v, sau đó tôi nhận xét bất kỳ vị trí nào trong mã nơi tôi nghĩ mình có thể trở lại trong 6 tháng và tự nghĩ với mình, "WTF".

Rõ ràng đây là chủ quan, nhưng tôi tò mò muốn biết nếu có ai có bất kỳ đối số hoặc kinh nghiệm thực sự tốt cho cách này hay cách khác.

Answer 1

Điều này đã được bàn đến chết.

Tôi sẽ chỉ cho bạn đến Jeff Atwood's wonderful post on the subject, chạm vào móng ngay trên đầu.

Answer 2

Thỉnh thoảng tôi chạy trên mã được phân vùng rất thanh lịch, có phương thức rõ ràng, tên trường và tên biến khác nhau mà mọi thứ tôi cần biết đều rõ ràng từ mã.

Trong trường hợp chung, chỉ có rất nhiều mã tuyệt vời viết mã như vậy. Phần còn lại của chúng tôi cùng nhau hợp tác với nhau.

• Nếu bạn là một chuyên gia mã thực sự tuyệt vời, đừng bận tâm bắt nạt mã thiêng liêng của bạn với những nhận xét không cần thiết.
• Nếu bạn hầu như không biết mình đang làm gì, hãy cẩn thận ghi lại các nỗ lực sai lầm của bạn để những người khác có thể cố gắng cứu vãn mớ hỗn độn.
• Nếu bạn trung bình (và hầu hết chúng ta, theo định nghĩa) thì hãy để lại một số gợi ý cho chính bạn và những người khác để giúp mọi thứ dễ dàng hơn trong thời gian bảo trì, nhưng không xúc phạm trí thông minh và không gian lãng phí của bất kỳ ai thực sự rõ ràng. Lý tưởng nhất là các nhận xét của bạn nên mô tả mã của bạn ở mức meta, cho biết bạn đang làm gì nhưng tại sao. Ngoài ra làm thế nào, nếu bạn đang làm một cái gì đó bất thường hoặc khó khăn.

Answer 3

Vấn đề với nhận xét là chúng có xu hướng tồn tại lâu sau khi mã được nhận xét đã thay đổi hoặc thậm chí bị xóa.

Theo quy tắc chung, tôi chỉ nhận xét API công khai và khó hiểu thuật toán.

Không sử dụng nhận xét để giải thích những gì bạn đã làm - đó là mã dành cho, sử dụng nhận xét để giải thích lý do bạn đã làm như vậy.

Answer 4

Bạn nên viết nhận xét trước mã hoặc trước hàm để lần sau nhìn vào hàm mà họ có thể biết ngay mục đích của mã đó là gì.
Điều đó xảy ra với tôi nhiều lần khi tôi viết mã và sau đó quên mục đích của nó. vì vậy, tôi có thói quen viết bình luận trước khi viết mã.

Answer 5

Điều tôi muốn thấy trong phần bình luận là giải thích tại sao một phương thức rõ ràng và đơn giản hơn nhiều so với phương thức được sử dụng trong mã không hoạt động.

Answer 6

Trong tất cả sự nghiệp của mình, tôi chưa bao giờ bắt gặp con thú tuyệt vời đó "mã tự viết". Có lẽ tôi đã không may mắn, nhưng tôi bắt đầu nghi ngờ nó không thực sự tồn tại.

Answer 7

"Một trong những khách hàng tiềm năng đã hướng dẫn các nhà phát triển của mình không sử dụng nhận xét vì chúng quá" lỗi thời "và một vài nhà phát triển khác đã chỉ ra rằng họ không bao giờ sử dụng nhận xét vì họ cảm thấy tất cả những gì họ làm là làm lộn xộn mã."

Nếu tôi từng nghe một nhà phát triển, tôi đã làm việc với việc nói chuyện như thế này, tôi sẽ sửa chúng. Nếu tôi không có thứ hạng cần thiết để sửa chúng, tôi sẽ rời khỏi công việc.

Rất ghi rõ mã, với định danh tốt - những thứ đôi khi được gọi là 'tự chủ tài liệu' - làm một công việc tốt để minh họa những gì đang làm. Đó là tốt như xa như nó đi. Công việc của các nhận xét là giải thích lý do tại sao.

Answer 8

chủ đề này có xu hướng được thảo luận rất nhiều, nhưng đây là Mỹ của tôi $ 0.02 về đề tài này:

1. Tôi thà thấy quá nhiều ý kiến ​​hơn là không đủ. Thất bại ở bất cứ điều gì, bạn luôn có thể xóa các nhận xét thừa từ mã; tuy nhiên, bạn không thể lấy được ý nghĩa từ chúng nếu không có gì để bắt đầu.
2. Tôi đã nghe một số nhà phát triển cho rằng các nhà phát triển khác rằng "trên tài liệu" (định nghĩa về điều này thay đổi theo từng người) mã của họ không phải là nhà phát triển giỏi. Trong khi nói rằng bạn đang cập nhật bộ đếm có thể là dấu hiệu cho thấy bạn không biết mình đang làm gì, có hướng dẫn rõ ràng về một số logic nghiệp vụ đang ngồi ở giữa phương pháp bạn đang làm việc có thể khá hữu ích.
3. Mặc dù có một số nhà phát triển xuất sắc có thể viết mã cực kỳ rõ ràng không yêu cầu nhận xét, hầu hết các nhà phát triển không giỏi hoặc dành nhiều thời gian viết mã để tự viết tài liệu hơn họ bao gồm một vài bình luận.
4. Bạn không biết cấp độ kỹ năng của người tiếp theo để đọc mã của bạn và nếu cấu trúc ngôn ngữ bạn đang sử dụng có thể gây nhầm lẫn, thường là một ý tưởng hay để bao gồm nhận xét mà ai đó có thể sử dụng cho Google.

Answer 9

Diomidis Spinellis chỉ viết một cột đẹp cho IEEE cột (quoted on his blog), nêu rõ các vấn đề, và một số giải pháp:

Khi nhận xét, chúng tôi luôn luôn là một cặp vợ chồng của tổ hợp phím ra khỏi thảm họa: khôi phục chức năng của mã trong tiếng Anh. Và đó là khi sự cố bắt đầu.