Làm cách nào để ghi lại các API thử nghiệm hoặc chưa hoàn chỉnh như @deprecated?


12

Có một thuật ngữ tốt tương tự nhưng khác với "không dùng nữa" có nghĩa là một phương thức hoặc API nằm trong cơ sở mã nhưng không nên được sử dụng vì việc triển khai của nó không hoàn thành hoặc có thể sẽ thay đổi? (Vâng, tôi biết, những phương pháp đó không nên công khai, yada yada yada. Tôi đã không tạo ra tình huống của mình, tôi chỉ đang cố gắng làm cho nó tốt nhất.)

Mọi người đề nghị gì? Thử nghiệm, chưa hoàn thành, còn gì nữa không?

Nếu tôi đang xây dựng tài liệu javadoc cho API này vẫn còn thay đổi, tôi có nên sử dụng thẻ @deprecated hay có quy ước nào tốt hơn không? Đối với tôi @deprecated ngụ ý rằng API này đã cũ và cơ chế ưa thích mới hơn có sẵn. Trong tình huống của tôi, không có lựa chọn nào khác, nhưng một số phương thức trong API chưa kết thúc và vì vậy không nên sử dụng. Tại thời điểm này tôi không thể đặt chúng ở chế độ riêng tư, nhưng tôi muốn đưa ra những cảnh báo rõ ràng trong các tài liệu.


Thẻ "Không ổn định" cũng sẽ hữu ích. Ý nghĩa sẽ là một cái gì đó khác biệt. "Điều này được cho là hoạt động tốt nhưng chúng tôi có thể thực hiện một số thay đổi trong tương lai".
Borjab

Câu trả lời:


8

Thuật ngữ phù hợp rất có thể là vườn ươm , đây là thuật ngữ được Google và Apache sử dụng:

  • google-web-toolkit-vườn ươm

    Vườn ươm chính thức của các widget và thư viện cho Google Web Toolkit ...

  • Vườn ươm Apache

    ... Cổng thông tin cho các dự án nguồn mở dự định trở thành các dự án Quỹ phần mềm Apache hoàn chỉnh ...

Nếu bạn xem xét kỹ hơn các dự án được đề cập ở trên, bạn có thể nhận thấy rằng các API "thử nghiệm" (ví dụ như trong GWT) có xu hướng có các tên gói "dành riêng", như com.google.gwt.gen2. Điều này là để tránh gây ô nhiễm API "hoàn thiện" trong tương lai dành cho tiêu dùng công cộng vĩnh viễn - bởi vì, bạn biết đấy,

"API công khai, giống như kim cương, là mãi mãi. Bạn có một cơ hội để làm cho đúng, vì vậy hãy cố gắng hết sức ..." (Joshua Bloch, Cách thiết kế API tốt và tại sao lại có vấn đề )


2
Tôi đã nghiêng về "Thử nghiệm" sau khi thấy các API như developer.chrome.com/extensions/experimental.html
Michael Levy

10

Tôi sẽ sử dụng @deprecatedcho lý do hoàn toàn thực tế.

Mặc dù @deprecatedkhông truyền đạt ý nghĩa chính xác mà bạn muốn, nhưng nó có một lợi thế đáng kể: Trình biên dịch Java có hỗ trợ tích hợp cho nó. Biên dịch bằng -deprecationcờ cho phép bạn tìm thấy tất cả các địa điểm nơi bạn ghi đè phương thức không dùng nữa, giúp người dùng của bạn tìm thấy mã đáng ngờ rất nhanh. Bạn có thể sử dụng @deprecatedthẻ Javadoc để giải thích những gì đang thực sự xảy ra với bất kỳ ai quan tâm đọc tài liệu của bạn. Đây là nơi bạn có thể nói với người dùng rằng API là thử nghiệm, nên tự chịu rủi ro khi sử dụng, v.v.


1
+1. Điểm tuyệt vời. Có hỗ trợ tích hợp là điều cần thiết cho các phần như vậy của API và khuyến khích người dùng xem tài liệu để hiểu tại sao những phần đó được đánh dấu là khấu hao.
Arseni Mourzenko

2
Tôi đã nghiêng về một cái gì đó như "* @deprecated Đây là một API thử nghiệm và có khả năng thay đổi" ở mức tối thiểu để có được IDE và các tài liệu làm nổi bật phương thức và sau đó có một lời giải thích ngắn gọn.
Michael Levy

Chỉ cần nhớ rằng không tán thành sẽ tạo ra rất nhiều cảnh báo. Điều này có thể không tệ như nó có vẻ. Được cảnh báo về các tính năng thử nghiệm có thể ổn.
Borjab

3

Tôi chưa bao giờ thấy bất cứ điều gì như thế này trong các API khác, vì các tính năng thử nghiệm hoặc chưa hoàn chỉnh không có gì để làm trong API công khai.

Vì bạn không có lựa chọn nào khác, chỉ cần đưa ra một cảnh báo rõ ràng rằng phần API có thể thay đổi.


Tốt. Ví dụ: chúng tôi có: junit.org/apidocs/org/junit/experimental/package-summary.html Nhân tiện , sử dụng gói là một ý tưởng tuyệt vời. Khi API không ổn định, bạn cần thay đổi gói để bạn vi phạm tất cả các phụ thuộc. Một chú thích java sẽ tốt hơn nhiều
Borjab
Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.