Có cần thiết phải viết bình luận javadoc cho MỌI tham số trong chữ ký của phương thức không?

Một trong những nhà phát triển trong nhóm của tôi tin rằng cần phải viết bình luận javadoc cho MỌI tham số trong chữ ký của phương thức. Tôi không nghĩ rằng điều này là cần thiết và thực tế tôi nghĩ nó thậm chí có thể gây hại.

Trước hết, tôi nghĩ tên tham số nên được mô tả và tự ghi lại. Nếu nó không rõ ràng ngay lập tức những thông số của bạn là gì, thì có lẽ bạn đang làm sai. Tuy nhiên, tôi hiểu rằng đôi khi không rõ tham số đó dùng để làm gì, vì vậy trong những trường hợp đó, vâng, bạn nên viết bình luận javadoc giải thích tham số.

Nhưng tôi nghĩ không cần thiết phải làm điều đó cho MỌI tham số. Nếu rõ ràng tham số này dùng để làm gì, bình luận javadoc là không cần thiết; bạn chỉ đang tạo thêm công việc cho chính mình. Hơn nữa, bạn đang tạo thêm công việc cho bất cứ ai phải duy trì mã của bạn. Các phương thức thay đổi theo thời gian và duy trì các bình luận cũng quan trọng như việc duy trì mã của bạn. Đã bao nhiêu lần bạn thấy một bình luận như "X không Y vì lý do Z" chỉ để thấy rằng bình luận đó đã lỗi thời và trên thực tế, phương thức này thậm chí không còn lấy tham số X nữa? Nó xảy ra mọi lúc, vì mọi người quên cập nhật ý kiến. Tôi sẽ lập luận rằng một bình luận sai lệch có hại hơn là không có bình luận nào cả. Và do đó, có nguy cơ bình luận quá mức: bằng cách tạo tài liệu không cần thiết, bạn '

Tuy nhiên, tôi tôn trọng nhà phát triển khác trong nhóm của tôi và chấp nhận rằng có lẽ anh ấy đúng và tôi sai. Đó là lý do tại sao tôi mang câu hỏi của mình cho bạn, các nhà phát triển đồng nghiệp: Có thực sự cần thiết phải viết bình luận javadoc cho MỌI tham số không? Giả sử ở đây rằng mã là nội bộ đối với công ty của tôi và sẽ không được sử dụng bởi bất kỳ bên ngoài nào.

Các chú thích Javadoc (và, trong từ Microsoft, XMLDoc) không phải là các bình luận , chúng là tài liệu .

Nhận xét có thể thưa thớt như bạn muốn chúng được; giả sử mã của bạn có thể đọc được một nửa, thì các bình luận thông thường chỉ là các biển chỉ dẫn để hỗ trợ các nhà phát triển trong tương lai hiểu / duy trì mã mà họ đã nhìn chằm chằm trong hai giờ.

Các tài liệu đại diện cho một hợp đồng giữa một đơn vị mã và người gọi của nó. Nó là một phần của API công khai. Luôn giả định rằng Javadoc / XMLdoc sẽ kết thúc trong tệp trợ giúp hoặc trong cửa sổ bật lên tự động hoàn thành / intellisense / hoàn thành mã và được quan sát bởi những người không kiểm tra phần bên trong mã của bạn mà chỉ muốn sử dụng nó cho mục đích nào đó của riêng họ.

Tên đối số / tham số không bao giờ tự giải thích. Bạn luôn nghĩ rằng họ là khi bạn đã dành cả ngày qua để làm việc với mã, nhưng hãy thử quay lại sau kỳ nghỉ 2 tuần và bạn sẽ thấy họ thực sự vô ích như thế nào.

Đừng hiểu lầm tôi - điều quan trọng là chọn tên có ý nghĩa cho các biến và đối số. Nhưng đó là một mối quan tâm mã, không phải là một mối quan tâm tài liệu. Đừng hiểu cụm từ "tự ghi chép" theo nghĩa đen; điều đó có nghĩa là trong bối cảnh của tài liệu nội bộ (ý kiến), không phải tài liệu bên ngoài (hợp đồng).

Hoặc bình luận mọi thứ hoặc bình luận không có gì (rõ ràng bình luận mọi thứ là một lựa chọn tốt hơn nhiều). Hãy suy nghĩ về ai đó sử dụng mã của bạn, hoặc xem xét API trực tiếp trong tệp nguồn của bạn hoặc trong tệp tài liệu được tạo (nghĩa là đầu ra doxygen). Sự không nhất quán thường dẫn đến sự nhầm lẫn, dẫn đến thời gian đào bới nguồn để tìm hiểu lý do tại sao một cái gì đó không được bình luận, dẫn đến lãng phí thời gian có thể tránh được nếu tham số chỉ được nhận xét ở vị trí đầu tiên.

Hãy nhớ rằng: Điều gì đó có ý nghĩa đối với bạn có thể được người khác diễn giải hoàn toàn khác, bất kể bạn nghĩ nó trần tục đến mức nào (hãy nghĩ về một người không mạnh về đọc tiếng Anh và cố gắng hiểu mã của bạn).

Đã nói tất cả những điều đó, nếu nhà phát triển khác đang nhấn mạnh tầm quan trọng của việc ghi lại tất cả mọi thứ, thì cũng cần nhấn mạnh nhiều (nếu không muốn nói thêm) để giữ cho tài liệu được cập nhật. Như bạn đã nói, không có gì tồi tệ hơn việc có những bình luận lỗi thời (cũng tệ như vậy, nếu không nói là tệ hơn những tài liệu bị bỏ qua).

Hãy bắt đầu từ giả định rằng chu kỳ của nhà phát triển là tài nguyên mà chúng tôi đang cố gắng bảo tồn.

Vì vậy, điều đó có nghĩa là các nhà phát triển không nên lãng phí thời gian để ghi lại các tham số tự hiển thị và trả về giá trị, phải không?

Vâng, hãy phá vỡ nó.

Nếu chúng tôi ghi lại tất cả mọi thứ, giả sử các bình luận cận biên thực sự là tầm thường và không cần suy nghĩ hay nghiên cứu, thì chi phí là thời gian được thêm vào để thực sự gõ bình luận và sửa lỗi chính tả.

Nếu chúng ta chọn và chọn, thì chi phí là:

• Có và chiến thắng cuộc tranh luận với (các) nhà phát triển khác trong nhóm của bạn, những người nghĩ rằng mọi thứ nên được ghi lại.
• Đối với mỗi tham số, xác định xem điều này nên hay không nên được ghi lại.
• Nhiều tranh luận hơn với nhóm của bạn khi ai đó có ý kiến ​​khác về việc một tham số có nên được ghi lại hay không.
• Thời gian dành cho việc tìm kiếm mã và nghiên cứu khi một tham số được coi là tự giải thích hóa ra không phải như vậy.

Vì vậy, tôi sẽ nghiêng về tài liệu mọi thứ. Nhược điểm là xác định, nhưng được chứa đựng.

Nếu bạn đang viết Javadoc, bạn cũng có thể viết nó hoàn toàn, thậm chí bao gồm cả các tham số "rõ ràng". Chúng có thể rõ ràng đối với bạn hoặc nhà phát triển khác, nhưng bất kỳ ai mới đang xem xét nó sẽ được lợi từ việc biết ý định của từng tham số.

Để duy trì Javadoc đúng cách, bạn cần sử dụng các công cụ để phát triển giúp bạn thực hiện điều này. Nhật thực đến với tâm trí. Tất nhiên, nếu nó quan trọng, bạn phải đảm bảo rằng tất cả mọi người trong nhóm thực hiện phần của họ để duy trì mã, bao gồm cả các nhận xét.

Đừng quên rằng javadoc có thể được hiển thị trong khi tách biệt với mã, ví dụ điển hình là chính API Java . Bằng cách không bao gồm javadoc cho mọi tham số trong một phương thức, bạn đang trình bày sai phương thức và cách sử dụng nó.

"Cần thiết" là hoàn toàn chủ quan. Tôi nghĩ những gì bạn đang hỏi là, 'trong tình huống của bạn, bạn nên thêm một bình luận javadoc'. Không biết phạm vi hoặc bối cảnh của ứng dụng của bạn, làm thế nào để chúng tôi biết những gì phù hợp với bạn?

Nếu mã phải đối mặt công khai này (nghĩa là mã có nghĩa là cho người khác truy cập, chẳng hạn như api) thì có, ghi lại từng tham số. Đừng cho rằng người đọc biết về dự án nhiều như bạn làm. Nhưng nếu không, tùy thuộc vào bạn và nhóm của bạn để đưa ra quyết định của riêng bạn.