Tôi muốn viết Javadoc theo cách DRY. Nhưng tài liệu tiên tri về Javadoc nói viết lại điều tương tự trong bình luận phương thức quá tải. Tôi không thể tránh sự lặp lại?
Tôi muốn viết Javadoc theo cách DRY. Nhưng tài liệu tiên tri về Javadoc nói viết lại điều tương tự trong bình luận phương thức quá tải. Tôi không thể tránh sự lặp lại?
Câu trả lời:
Tôi rắc các {@inheritDoc}chỉ thị ở đây và ở đó trong các nhận xét Javadoc của mình khi ghi đè các phương thức từ các siêu lớp hoặc thực hiện các phương thức được xác định giao diện.
Điều này hoạt động tốt với tôi ít nhất, tránh sự lặp lại trong mã nguồn và bạn vẫn có thể thêm thông tin cụ thể vào nhận xét Javadoc cụ thể nếu có nhu cầu làm như vậy. Tôi không coi thực tế là bản thân nhận xét Javadoc là bất kỳ vấn đề nào khi tất cả những gì cần có trong một IDE tốt là di chuột qua tên định danh liên quan để lấy Javadoc được hiển thị với tất cả các tham chiếu.
Điểm của tài liệu là để chiếu sáng người dùng trong tương lai của một mặt hàng. Điều này một phần vì sự thuận tiện của tác giả, để người đó không phải liên lạc bất cứ khi nào ai đó không thể tìm ra cách thức hoạt động của sự việc. Hầu hết, tuy nhiên, nó là vì lợi ích của những người cần sử dụng hoặc hỗ trợ điều này.
Như vậy, điểm cần phải rõ ràng, trái ngược với sự thuận tiện cho tác giả. Bạn không thể mong đợi mọi người săn lùng lên xuống thông qua tài liệu API của bạn vì về cơ bản bạn quá lười biếng để lặp lại chính mình. Suck it up - Javadoc sẽ lặp đi lặp lại.
Điều đó nói rằng, không có lý do gì, nếu bạn thông minh, bạn không thể viết một chương trình sẽ gắn nhận xét vào mã của bạn dựa trên các điểm đánh dấu hoặc một số tiêu chí khác. Nó có thể rắc rối hơn giá trị của nó. Hay không.