Thực tiễn chính xác để thêm nhận xét Javadoc vào giao diện và thêm nhận xét không phải Javadoc trong quá trình triển khai?Nhận xét Javadoc có nên được thêm vào quá trình triển khai không?
Hầu hết các IDE tạo nhận xét không phải JavaDoc để triển khai khi bạn tự động tạo nhận xét. Không nên phương pháp cụ thể có mô tả?
Đối với các phương pháp chỉ thực hiện (không ghi đè), chắc chắn, tại sao không, đặc biệt nếu chúng được công khai.
Nếu bạn có tình huống quan trọng và bạn sẽ sao chép bất kỳ văn bản nào, thì chắc chắn là không. Nhân rộng là một cách chắc chắn gây ra sự khác biệt. Kết quả là, người dùng sẽ có một sự hiểu biết khác nhau về phương pháp của bạn dựa trên việc họ kiểm tra phương thức trong siêu loại hoặc loại phụ. Sử dụng @inheritDoc hoặc không cung cấp tài liệu - Các IDE sẽ lấy văn bản có sẵn thấp nhất để sử dụng trong chế độ xem Javadoc của chúng.
Là một sang một bên, nếu phiên bản ghi đè của bạn thêm nội dung vào tài liệu của siêu kiểu, bạn có thể đang gặp rắc rối. Tôi đã nghiên cứu vấn đề này trong tiến sĩ của tôi và thấy rằng nói chung folks sẽ không bao giờ nhận thức được các thông tin bổ sung trong phiên bản trọng nếu họ đang gọi thông qua một supertype.
Giải quyết vấn đề này là một trong những tính năng chính của công cụ nguyên mẫu mà tôi đã xây dựng - Bất cứ khi nào bạn gọi một phương pháp, bạn sẽ có chỉ báo nếu mục tiêu của nó hoặc bất kỳ mục tiêu ghi đè tiềm năng nào chứa thông tin quan trọng (ví dụ: một hành vi xung đột). Ví dụ, khi gọi đặt trên bản đồ, bạn đã được nhắc nhở rằng nếu triển khai của bạn là một TreeMap, các phần tử của bạn cần phải được so sánh.
Cả việc triển khai và giao diện nên có javadoc. Với một số công cụ, bạn có thể kế thừa tài liệu của giao diện bằng từ khóa @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
Vì lợi ích của việc tạo javadoc, điều đó có quan trọng không. Nếu bạn khai báo các tham chiếu đến một triển khai cụ thể bằng cách sử dụng chỉ giao diện thì nó không vì các phương thức của giao diện sẽ được lấy bởi IDE.
@see Nó tạo liên kết đến mô tả trong giao diện. Nhưng tôi nghĩ tốt hơn là nên thêm một số chi tiết về quá trình triển khai.
IMO bằng cách sử dụng' @ see' liên kết với phương thức giao diện là một thực hành tốt và nó là đủ trong hầu hết các trường hợp . Khi bạn sao chép javadoc từ phương thức giao diện đến triển khai cụ thể, bạn chỉ cần sao chép thông tin và nó có thể nhanh chóng trở nên không nhất quán. Tuy nhiên, bất kỳ thông tin bổ sung nào về việc triển khai sẽ được thêm vào javadoc. – Piotr
Tài liệu bổ sung không phải là về sao chép tài liệu từ giao diện, mà chỉ để giải thích cách bạn triển khai phương thức và nội dung như vậy. Với một tài liệu giao diện, bạn giải thích kết quả/mục tiêu (trạng thái ứng dụng hoặc phương thức trả về) trong khi thực hiện nó có thể là tốt để giải thích cách bạn đạt được mục tiêu này. – redben
thực hành Hơi tốt là đặt
/**
* {@inheritDoc}
*/
như javadoc thực hiện của (trừ khi có điều gì đó thêm để được giải thích về các chi tiết của việc thực hiện).
Điểm có giao diện là phương thức có thể được triển khai theo nhiều cách. Nếu tôi chỉ định thừa kế các nhận xét, thì điểm nào trong việc có nhận xét trong việc thực hiện? –
Tôi sử dụng thẻ ở trên và sau đó đặt bất kỳ tài liệu bổ sung bắt buộc nào bên dưới thẻ. –
Sjoerd nói chính xác rằng cả giao diện và triển khai phải có JavaDoc. Giao diện JavaDoc nên xác định hợp đồng của phương thức - phương thức nên làm, những gì đầu vào cần, giá trị nó sẽ trả về, và nó nên làm gì trong trường hợp lỗi.
Tài liệu triển khai cần lưu ý các tiện ích mở rộng hoặc hạn chế về hợp đồng và các chi tiết thích hợp về việc triển khai, đặc biệt là hiệu suất.
Nói chung, khi bạn ghi đè phương thức, bạn tuân theo hợp đồng được xác định trong lớp cơ sở/giao diện, do đó bạn không muốn thay đổi javadoc gốc. Do đó, việc sử dụng thẻ @inheritDoc hoặc @see được đề cập trong các câu trả lời khác là không cần thiết và thực sự chỉ đóng vai trò là tiếng ồn trong mã.Tất cả các công cụ hợp lý kế thừa phương pháp javadoc từ lớp cha hoặc giao diện theo quy định here:
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface
Thực tế là một số công cụ (! Tôi đang nhìn bạn, Eclipse) tạo ra những theo mặc định khi trọng một phương pháp duy nhất là buồn trạng thái của sự vật, nhưng không biện minh cho việc xáo trộn mã của bạn bằng tiếng ồn vô dụng.
Có thể tất nhiên là trường hợp ngược lại, khi bạn thực sự muốn thêm một bình luận cho phương pháp trọng (thường là một số chi tiết thực hiện bổ sung hoặc làm hợp đồng chặt chẽ hơn một chút). Nhưng trong trường hợp này, bạn hầu như không bao giờ muốn làm điều gì đó như thế này:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/
Tại sao? Vì nhận xét được kế thừa có thể rất dài. Trong trường hợp như vậy, ai sẽ nhận thấy câu bổ sung ở cuối của 3 đoạn văn dài ?? Thay vào đó, chỉ cần viết xuống phần bình luận của bạn và đó là tất cả. Tất cả các công cụ javadoc luôn hiển thị một số loại Được chỉ định bởi liên kết mà bạn có thể nhấp để đọc nhận xét của lớp cơ sở. Không có điểm nào trong việc trộn chúng.
Đây là câu trả lời đúng duy nhất ở đây! – user219882
Bạn chưa biết rằng các yếu tố cần phải được so sánh khi sử dụng một TreeMap? Triển khai cũng không nên triển khai hành vi xung đột. –
Tôi nghĩ đây là câu trả lời đúng http://stackoverflow.com/a/39981265/419516 – user219882