Есть ли хороший термин, который похож, но отличается от «не рекомендуется», чтобы означать, что метод или API находятся в базе кода, но не должны использоваться, потому что их реализация не завершена или, вероятно, изменится? (Да, я знаю, эти методы не должны быть общедоступными, яда, яда, яда. Я не создавал свою ситуацию, я просто пытался извлечь из этого максимум пользы).
Что люди предлагают? Экспериментальный, неполный, что-то еще?
Если я создаю документацию по Javadoc для этого API, которая все еще находится в процессе разработки, должен ли я использовать тег @deprecated или есть лучшее соглашение? Для меня @deprecated подразумевает, что этот API старый и доступен более новый предпочтительный механизм. В моей ситуации альтернативы нет, но некоторые методы в API не завершены и поэтому не должны использоваться. На данный момент я не могу сделать их конфиденциальными, но я хотел бы поместить четкие предупреждения в документы.
Ответы:
Подходящий термин, скорее всего, инкубатор , этот термин используют Google и Apache:
Google-веб-инструментарий-инкубатор
Apache Incubator
Если вы внимательно посмотрите на проекты, упомянутые выше, вы можете заметить, что «экспериментальные» API (например, в GWT), как правило, имеют «выделенные» имена пакетов, например
com.google.gwt.gen2
. Это сделано для того, чтобы не загрязнять будущий «доработанный» API, предназначенный для постоянного общественного потребления, - потому чтоисточник
Я бы использовал
@deprecated
по чисто практическим соображениям.Хотя
@deprecated
он и не дает точного значения, которое вы хотели бы получить, у него есть существенное преимущество: компилятор Java имеет встроенную поддержку. Компиляция с-deprecation
флагом позволяет найти все места, где вы переопределяете устаревший метод, помогая вашим пользователям очень быстро находить подозрительный код. Вы можете использовать@deprecated
тег Javadoc, чтобы объяснить, что на самом деле происходит, всем, кто хочет прочитать вашу документацию. Здесь вы можете сказать пользователю, что API является экспериментальным, его следует использовать на свой страх и риск и так далее.источник
Я никогда не видел ничего подобного в других API, поскольку экспериментальные или неполные функции не имеют ничего общего с публичным API.
Поскольку у вас нет выбора, просто поместите четко видимое предупреждение о том, что часть API может быть изменена.
источник