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

Question

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

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

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

/ JaanusSiim

Answer 1

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

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

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

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

Answer 2

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

Раймонд Чен лучше всех отвечает в своем блоге о Win32 API,

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

Answer 3

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

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

Answer 4

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

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

Answer 5

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

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

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

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

Answer 6

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

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

Answer 7

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

Answer 8

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

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