Việ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 có đúng không?
Hầu hết các IDE tạo nhận xét không phải JavaDoc cho các triển khai khi bạn tự động tạo nhận xét. Phương pháp cụ thể không nên có mô tả?
Câu trả lời:
Đối với các phương thức chỉ thực thi (không phải ghi đè), chắc chắn, tại sao không, đặc biệt nếu chúng là công khai.
Nếu bạn gặp phải tình huống ghi đè và bạn sẽ sao chép bất kỳ văn bản nào, thì chắc chắn là không. Sao chép là một cách chắc chắn để gây ra sự khác biệt. Do đó, người dùng sẽ có cách hiểu 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 kiểu siêu hay kiểu con. Sử dụng @inheritDochoặc không cung cấp tài liệu - IDE sẽ lấy văn bản thấp nhất có sẵn để sử dụng trong chế độ xem Javadoc của họ.
Ngoài ra, nếu phiên bản ghi đè của bạn thêm nội dung vào tài liệu của supertype, bạn có thể gặp rắc rối. Tôi đã nghiên cứu vấn đề này trong thời gian tiến sĩ của mình và thấy rằng nói chung mọi người sẽ không bao giờ nhận thức được thông tin bổ sung trong phiên bản ghi đè nếu họ đang gọi thông qua một siêu kiểu.
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 thức, bạn sẽ nhận đượ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ụ: hành vi xung đột). Ví dụ: khi gọi đặt trên bản đồ, bạn được nhắc rằng nếu việc triển khai của bạn là Sơ đồ cây, các phần tử của bạn cần phải được so sánh với nhau.
Cả quá trình thực hiện và giao diện phải 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 với từ khóa @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
{@inheritDoc}và nó chỉ hoạt động nếu bạn không có chú thích @Overrideđầu tiên
Thực hành tốt là đặt
/**
* {@inheritDoc}
*/
như javadoc của triển khai (trừ khi có điều gì đó cần giải thích thêm về chi tiết của triển khai).
Nói chung, khi bạn ghi đè một phương thức, bạn tuân thủ hợp đồng được xác định trong lớp cơ sở / giao diện, vì vậy bạn không muốn thay đổi javadoc gốc bằng mọi cách. Do đó, việc sử dụng @inheritDochoặc @seethẻ đượ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ò như một nhiễu trong mã. Tất cả các công cụ hợp lý đều kế thừa phương thức javadoc từ lớp cha hoặc giao diện như được chỉ định ở đây :
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 các công cụ này theo mặc định khi ghi đè một phương thức chỉ là một trạng thái đáng buồn, nhưng không biện minh cho việc làm lộn xộn mã của bạn với tiếng ồn vô ích.
Tất nhiên có thể xảy ra trường hợp ngược lại, khi bạn thực sự muốn thêm nhận xét vào phương thức ghi đè (thường là một số chi tiết triển khai bổ sung hoặc làm cho 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? Bởi vì nhận xét kế thừa có thể rất dài. Trong trường hợp như vậy, ai sẽ để ý câu thừa ở cuối 3 đoạn văn dài ?? Thay vào đó, chỉ cần viết ra phần nhận xét của riêng bạn và thế thôi. Tất cả các công cụ javadoc luôn hiển thị một số loại Được chỉ định bằng liên kết mà bạn có thể nhấp vào để đọc nhận xét của lớp cơ sở. Không có ích gì khi trộn chúng.
@see Nó tạo liên kết đến mô tả trong giao diện. Nhưng tôi nghĩ cũng tốt nếu thêm một số chi tiết về việc thực hiện.
@seeliên kết đến các phương thức giao diện là một phương pháp hay 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 sang triển khai cụ thể, bạn chỉ 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 phải được thêm vào javadoc.
Sjoerd nói một cách chính xác rằng cả giao diện và triển khai đều 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 phải làm gì, nó nhận những đầu vào nào, giá trị nào nó phải trả về và nó phải làm gì trong trường hợp có lỗi.
Tài liệu thực hiện cần lưu ý các phần mở rộng hoặc hạn chế đối với hợp đồng, cũng như các chi tiết thích hợp về việc thực hiện, đặc biệt là hiệu suất.
Vì lợi ích của javadoc được tạo ra, nó không quan trọng. Nếu bạn khai báo các tham chiếu đến một triển khai cụ thể chỉ sử dụng giao diện thì không vì các phương thức của giao diện sẽ được IDE truy xuất.