спецификации, руководства, описания, API

Тег @deprecated

"@deprecated": Механическая Справка для Отказа от Старых API

Джон Р. Роуз
4 октября 1996

Проблема:

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

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

Детали:

В пределах комментариев для документации мы определяем новый тег абзаца "@deprecated". (См. Спецификацию языка Java.) Это может появиться и в class и в задействованных комментариях для документации, и применит определенно конструкцию, которую представляет его комментарий.

Теговый абзац может быть пустым. Если это не, это должно сказать программисту, как избегать использования осуждаемой функции.

Должен быть "@see" теговые абзацы, которые относятся к новым версиям той же самой функциональности.

Насколько компилятор затрагивается, присутствие строки "@deprecated" в начале строки комментария для документации (за исключением пробела) заставляет его помещать "Осуждаемый" атрибут в вывод classfile для соответствующего class, поля, или метода.

Кроме того, параллельно с логикой проверки доступа для классов и элементов, компилятор ищет "Осуждаемые" атрибуты классов и элементов, получаемых доступ, и выпускает предупреждения, когда осуждаемые классы или элементы используются.

Отметьте, что осуждение применяется к классам и к отдельным элементам, не к их именам. Для единственного метода возможно осудить и неосудить перегрузки. Для неосуждаемого элемента возможно скрыть или переопределить осуждаемый, который удаляет осуждение. Это - обязанность программиста осудить переопределения осуждаемого метода, если фактически они должны быть осуждены.

Осуждение, предупреждающее, подавляется, если единица компиляции, содержащая осуждение, компилируется одновременно как единица компиляции, используя осуждаемый class или элемент. Это позволяет API наследства быть созданными без предупреждений. В настоящий момент нет никакого другого способа подавить предупреждения осуждения.

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

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

Практика:

Вот пример наиболее распространенной формы осуждаемого метода:

    /**
     * @deprecated
     * @see #getPreferredSize
     */
    public Dimension preferredSize() {
        return getPreferredSize();
    }

(Примечания: тег "@deprecated" должен сопровождаться пространством или новой строкой. Тег "@see" должен быть в начале строки. См. Спецификацию языка Java.)

Если осуждение является простым переименованием, нет никакой потребности сказать, что что-то как "этот метод заменяется getPreferredSize"; "@see" - теговый абзац указывает на пользователя на замену.

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

    /**
     * Delete multiple items from the list.
     *
     * @deprecated  Not for public use in the future.
     * This method is expected to be retained only as a package
     * private method.
     * @see #remove(int)
     * @see #removeAll()
     */
    public synchronized void delItems(int start, int end) {
    ...
    }

Разработчики новых 1.1 API должны тщательно рассмотреть, заменяют ли они старые API. Для каждого такого API, если они хотят поощрить пользователей старого предыдущего API переходить на новый API, они должны добавить абзац осуждения к комментарию для документации. Пустые абзацы осуждения являются невоспитанностью, потому что они не помогают пользователю фиксировать предупреждения, которые являются результатом осуждения.

Допустимые причины пожелания, чтобы пользователи перешли на новый API, включают:

старый API небезопасен, ошибочен, или очень неэффективен
старый API уходит в будущем выпуске
старый API поощряет очень плохо кодировать методы

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

(Вероятно, не хорошо определенно упомянуть расписание для постепенного сокращения осуждаемого API; это - бизнес-решение, которое должно быть передано другие пути.)

Не необходимо осудить отдельные элементы осуждаемого class, если, конечно, программист не хочет объяснить некоторый конкретный вопрос об одном элементе.

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

Другие Проектные решения:

Это - первый раз, когда компилятор всегда осведомлен о содержании комментария документа. (Однажды, это удостоверилось, что они были в правильном месте в дереве синтаксического анализа, но это больше не истина.) Мы слегка не хотели делать поведение компилятора зависящим от содержания комментария.

Один прецедент для того, чтобы изучить комментарии является "линтом", который использует комментарии как/*PRINTFLIKE2*/, чтобы аннотировать API C.

Отметьте, что комментарии для документации Java структурируются, и структура определяется в Спецификации языка Java. Это означает, что нам "принадлежит" формат этого определенного вида комментария, таким образом, наш проект несколько более разумен чем менее дифференцируемые соглашения, используемые линтом.

Мы рассматривали прагмы представления, и использование их для осуждения (например, <*deprecated *>), но это откроет дверь, очень широкую для многих видов несовместимых расширений и, возможно, к серьезным злоупотреблениям.

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

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

Мы рассматривали представление нового ключевого слова, чего-то как "переходный процесс". Это решило бы механическую неисправность, но за счет изменения языка непосредственно. В частности мы должны были бы убрать идентификатор из кодеров, которые мы ранее не зарезервировали (как "var"). Кроме того, так как основная аудитория осуждений является людьми, основанный на ключевом слове подход недостаточен, и должен быть увеличен соглашениями комментария, предпочтительно, которые интегрируют с javadoc. Таким образом подход ключевого слова не платит.

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

Свяжитесь с Нами