Як документувати експериментальні чи неповні API, такі як @deprecated?

12

Чи є хороший термін, схожий, але відмінний від "застарілого", щоб означати, що метод або API є в кодовій базі, але його не слід використовувати, оскільки його реалізація не завершена або, ймовірно, зміниться? (Так, я знаю, ці методи не повинні бути загальнодоступними, яда яда яда. Я не створив свою ситуацію, я просто намагаюся зробити все найкраще.)

Що пропонують люди? Експериментальне, неповне, щось інше?

Якщо я будую документацію javadoc для цього API, який все ще знаходиться в потоці, чи слід використовувати тег @deprecated чи є краща умова? Для мене @deprecated означає, що цей API старий і доступний новіший бажаний механізм. У моїй ситуації альтернативи немає, але деякі методи в API не закінчені, і тому їх не слід використовувати. На даний момент я не можу зробити їх приватними, але я хотів би викласти чіткі застереження в документах.

— Майкл Леві
джерело

Тег "Нестабільний" також буде корисним. Сенс був би чимось різним. "Це повинно працювати нормально, але ми можемо внести деякі зміни в майбутньому".

— Борджаб

8

Відповідний термін - це, швидше за все, інкубатор , цей термін використовують Google і Apache:

google-web-toolkit-інкубатор

Офіційний інкубатор віджетів та бібліотек для веб-інструментів Google ...
Інкубатор Apache

... ворота для проектів з відкритим кодом, які мають намір стати повноцінними проектами Apache Software Foundation ...

Якщо ви більш детально подивіться на проекти, про які йдеться вище, ви можете помітити, що "експериментальні" API (наприклад, у GWT) мають тенденцію мати "виділені" назви пакетів, наприклад com.google.gwt.gen2. Це уникає забруднення майбутнього "доопрацьованого" API, призначеного для постійного суспільного споживання, тому що,

"Публічні API, як алмази, є назавжди. У вас є один шанс виправити це так, давайте все можливе ..." (Джошуа Блох, Як створити хороший API і чому це має значення )

— гнат
джерело

2

Я схилявся до "Експериментального" після перегляду таких API, як developer.chrome.com/extensions/experimental.html

— Майкл Леві

10

Я б використовував @deprecatedіз суто практичних причин.

Хоча @deprecatedне передає точного значення, яке б вам хотілося, воно має вагому перевагу: компілятор Java має вбудовану підтримку. Компіляція з -deprecationпрапором дає змогу знайти усі місця, де ви перекрили застарілий метод, допомагаючи вашим користувачам дуже швидко знайти підозрілий код. Ви можете скористатися @deprecatedтегом Javadoc, щоб пояснити, що насправді відбувається для кожного, хто хотів прочитати вашу документацію. Тут ви можете сказати користувачеві, що API експериментальний, його слід використовувати на власний ризик тощо.

— dasblinkenlight
джерело

1

+1. Відмінний момент. Вбудована підтримка є важливою для таких частин API і спонукає користувачів переглянути документацію, щоб зрозуміти, чому ці частини позначаються як амортизовані.

— Арсеній Муренко

2

Я схилявся до чогось на кшталт "* @deprecated Це експериментальний API і, ймовірно, зміниться" як мінімум, щоб отримати IDE та документи, щоб виділити метод, а потім мати коротке пояснення.

— Майкл Леві

Просто пам’ятайте, що застарілий призведе до появи багатьох попереджень. Це може бути не так погано, як здається. Попередившись про експериментальні можливості, може бути гаразд.

— Борджаб

3

Я ніколи не бачив нічого подібного в інших API, оскільки експериментальні або неповні функції не мають нічого спільного в публічному API.

Оскільки у вас немає вибору, просто поставте чітко видиме попередження про те, що частина API може змінюватися.

— Арсеній Муренко
джерело

Добре. Наприклад, у нас є: junit.org/apidocs/org/junit/experimental/package-summary.html До речі, використання пакету було надзвичайною ідеєю. Після того, як API нестабільний, вам потрібно змінити пакет, щоб ви порушили всі залежності. Анотація на Java була б набагато кращою

— Borjab