Как справиться с устареванием функций в библиотеке?

Question

Я работаю над библиотекой Java и хотел бы удалить из нее некоторые функции.Моя причина — общедоступный API и очистка дизайна.У некоторых объектов есть сеттеры, но они должны быть неизменяемыми, некоторые функции реализованы лучше/чище в разных методах и т. д.

Я пометил эти методы как устаревшие и хотел бы в конечном итоге удалить их.На данный момент я думаю об их удалении после нескольких спринтов (двухнедельных циклов разработки).

Существуют ли какие-либо «лучшие практики» по удалению избыточного общедоступного кода?

/ЯанусСийм

Answer 1

Установите дату и опубликуйте ее в теге @deprecated.Время, отведенное на удаление, зависит от количества пользователей вашего кода, того, насколько хорошо вы с ними связаны, и причины изменения.

Если у вас тысячи пользователей и вы почти не разговариваете с ними, временные рамки, вероятно, должны быть в диапазоне десятилетий :-)

Если вашими пользователями являются 10 ваших коллег и вы видите их ежедневно, временные рамки могут легко составлять несколько недель.

/**
 * @deprecated
 * This method will be removed after Halloween!
 * @see #newLocationForFunctionality
 */

Answer 2

Рассмотрим это так: клиент А загружает последнюю версию вашего библиотечного файла или фреймворка.Он запускает компиляцию на этой машине и внезапно видит тысячи ошибок, потому что файл-член или функция больше не существует.С этого момента вы даете клиенту причину, почему он не должен перейти на новую версию и оставить старую версию.

Рэймонд Чен лучше всего отвечает на этот вопрос в своем блоге о Win32 API:

Тем не менее, наш опыт работы в нашей компании по разработке программного обеспечения показывает, что после того, как API написан, мы должны донести его до конца жизненного цикла продукта.Чтобы помочь пользователям в новых версиях, мы обеспечиваем обратную совместимость со старыми командами в новой платформе.

Answer 3

Это зависит от того, как часто перестраивается код.Например, если библиотеку используют 4 приложения и они перестраиваются ежедневно, месяца будет достаточно, чтобы исправить устаревшие вызовы.

Кроме того, если вы используете устаревший тег, предоставьте комментарий о том, какой код заменяет устаревший вызов.

Answer 4

Использовать @устарело ярлык.Прочтите Устаревание API документ для получения дополнительной информации.

После того, как все, кто использует код, сообщат вам, что они очистили свою сторону, начните удалять устаревший код и подождите и посмотрите, не пожалуется ли кто-нибудь, а затем скажите им, чтобы он исправил свой собственный код...

Answer 5

Учитывая, что это библиотека, рассмотрите возможность архивирования версии с устаревшими функциями.Сделайте эту версию доступной как в исходном коде, так и в скомпилированной форме, в качестве резервного решения для тех, кто еще не модернизировал свой код для вашего нового API.(Двоичная форма необходима, потому что даже у вас могут возникнуть проблемы с компиляцией старой версии через несколько лет.) Дайте понять, что эта версия не будет поддерживаться и улучшаться.Пометьте эту версию символическим символом в вашей системе контроля версий.Затем двигайтесь вперед.

Answer 6

Это, безусловно, зависит от того, в каком масштабе используется ваш API и что вы заранее пообещали своим клиентам.

Как описал Винко Врсалович, вам следует ввести дату, когда следует ожидать отказа от функции.

В рабочей среде, если речь идет «просто» о том, чтобы получить более чистый код, я склонен оставлять все на месте даже после даты прекращения поддержки, если это ничего не нарушает.

С другой стороны, в разработке я делаю это немедленно, чтобы быстро разобраться во всем.

Answer 7

Возможно, вас заинтересуют примеры того, как работает устаревание в некоторых других проектах.Например, здесь следует то, что политика в проекте Django по прекращению поддержки функций является:

Второстепенный выпуск может утратить поддержку некоторых функций предыдущих выпусков.Если функция в версии A.B устарела, она продолжит работать в версии A.B+1.В версии A.B+2 использование этой функции вызовет предупреждение PendingDeprecationWarning, но продолжит работать.Версия A.B+3 полностью удалит эту функцию.

Answer 8

жаль, что вы не используете .Net :(

Встроенный Устаревший Атрибут генерирует предупреждения компилятора.