언제, 어떻게 API 를 비추천으로 할까 - xrath.com 에서 번역됨

# 언제, 어떻게 API 를 비추천으로 할까

비추천 API 에 관한
홈 페이지

- 「비추천」의 의미하는 것
- 언제 비추천으로 할까
- 비추천으로 하는 방법

- @Deprecated 주석의 사용
- @deprecated Javadoc 태그의 사용

## 「비추천」의 의미하는 것

「자학적 (self-deprecating) 유머」라고 하는 말을 (들)물었던 적이 있을지도 모릅니다. 즉, 자기 자신을 낮추는 유머입니다. 비추천 (deprecated)의 클래스 또는 메소드는, 거기에 닮았습니다. 이미 중요한 것은 없어졌습니다. 즉, 그 클래스나 메소드의 중요성은 현저하게 저하하고 있어 현재는 다른 클래스나 메소드로 옮겨져 있거나, 장래는 존재하지 않게 될 가능성도 있기 (위해)때문에, 향후는 사용해야 하는 것이 아닌 것을 의미하고 있습니다.

Java 에서는, 비추천을 표현하는 수단을 제공하고 있습니다. 그것은, 클래스의 발전에 수반해, 그 API (어플리케이션 프로그래밍 인터페이스)도 필연적으로 변화하기 때문입니다. 일관성을 유지하기 위해서(때문에) 메소드의 이름이 변경되거나 새로운 메소드나 개량판의 메소드가 추가되거나 필드가 변경이 되거나 합니다. 그러나, 이러한 변경에 의해 다른 문제도 생깁니다. 개발자가 새로운 API 로 이행할 때까지, 낡은 API 를 유지할 필요가 있는 한편으로, 향후는 낡은 API 를 사용해 프로그래밍을 실시하지 않게 전하지 않으면 안됩니다.

클래스나 메소드나 멤버 필드를 「비추천」이라고 하는 것으로써, 이 문제는 해결됩니다. Java 에서는, 비추천을 위한 2 개의 기구가 지원되고 있습니다. 1 개(살)은 주석 (J2SE 5.0 으로부터 지원되게 되었다)으로, 이제(벌써) 1 개(살)은 Javadoc 태그 (버젼 1.1 이래 지원되고 있다)입니다. 낡은 API 에 대한 기존의 호출도 계속해 기능합니다만, 주석에 의해, 컴파일러는 비추천의 프로그램 요소를 참조하고 있는 개소를 찾아냈을 때에 경고를 발행합니다. Javadoc 태그와 거기에 관련한 코멘트는, 비추천의 항목을 사용하지 않게 사용자에게 경고함과 함께, 대신에 무엇을 사용하면(자) 좋은가를 전합니다.

## 언제 비추천으로 할까

API 를 설계하려면 , 그 API 가 낡은 API 에 취해 대신하는 것이 될지 어떨지를 주의 깊게 검토합니다. 만약 취해 대신하는 것이어, 새로운 API 로 이행하도록(듯이) 개발자 (API 의 사용자)에게 추천 하는 경우에는, 낡은 API 를 비추천으로 합니다. 어느 API 를 비추천으로 하는 적절한 이유로서는, 다음과 같은 일이 생각됩니다.

- 안전하지 않은, 버그가 많아, 매우 비효율적이다
- 장래의 릴리스로 폐지된다
- 올바르지 않은 수법에서의 코딩으로 연결된다

상기의 어느 경우에도, 비추천이라고 하는 처치는 합리적인 선택입니다. 새로운 API 로 변경하도록(듯이) 개발자들을 촉구하고 있는 동안, 「하위 호환성」이 유지되기 때문입니다. 또, 개발자들이 언제 새로운 API 에 이행 할까를 결정하는 도움으로서 비추천이 된 기술적 이유를 코멘트에 간결하게 포함할 수도 있습니다.

비추천으로 하는 클래스의 개별의 멤버 필드 (프롭퍼티)에 대해서는, 어느 프롭퍼티에 대해 구체적인 설명을 더하고 싶은 경우를 제외해, 비추천 태그를 붙일 필요는 없습니다.

## 비추천으로 하는 방법

J2SE 5.0 으로부터는, 클래스, 메소드, 또는 필드를 비추천으로 하기 위해서(때문에),`@Deprecated` 주석을 사용할 수 있게 되었습니다. 게다가`@deprecated` Javadoc 태그를 사용해, 대신에 사용해야할 것을 개발자에게 지시할 수도 있습니다.

주석을 사용하면(자), 컴파일러는 비추천의 클래스, 메소드, 또는 필드가 사용되고 있는 경우에 경고를 생성합니다. 비추천 항목을 추천되어 있지 않은 엔티티내에서 사용했을 경우, 같은 가장 외측의 클래스내에서 사용했을 경우, 혹은 경고를 표시하지 않게 주석을 붙일 수 있었던 엔티티내에서 사용했을 경우, 컴파일러는 비추천에 관한 경고를 표시하지 않습니다.

Javadoc 의 `@deprecated` 태그를 사용할 때는, 새로운 API 의 사용 방법을 설명한 코멘트를 더하는 것을 강하게 추천합니다. 이것은, 개발자가 낡은 API 로부터 새로운 API 에의 효과적인 이행 방법을 결정하는 도움이 됩니다. 상세한 것에 대하여는,「`@Deprecated` Javadoc 태그의 사용」 을 참조해 주세요.

주 - Java 언어 스펙에서는,`@Deprecated` 주석이 기록된 클래스, 메소드, 또는 필드가 사용되었을 때에는, 컴파일러가 경고를 발행하도록(듯이) 정해져 있습니다. 한편,`@deprecated` Javadoc 태그로 마크 된 클래스, 메소드, 또는 필드가 사용되었을 때에 컴파일러가 경고를 발행해야 할 (일)것은 Java 언어 스펙에서는 정해져 있지 않습니다. 무엇보다, 현행의 Sun 컴파일러에서는, 이 태그가 사용되고 있는 경우에서도 경고는 발행됩니다. 다만, 향후도 Sun 의 컴파일러로 이러한 경고를 발행한다고 하는 보증은 없습니다.

### @Deprecated 주석의 사용

J2SE 5.0 에서는,주석 (메타데이타라고도 한다)으로 불리는 새로운 언어 기능이 도입되었습니다. Java 언어의 편입 주석의 1 개에 `@Deprecated` 주석이 있습니다. 이 주석을 사용하려면 , 클래스, 메소드, 또는 멤버의 선언전에 「@Deprecated」를 둘 뿐입니다.

`@Deprecated` 주석을 사용하면(자), 클래스, 메소드, 또는 필드가 비추천이 되어, 코드내에서 그 프로그램 요소가 사용되고 있는 경우에, 모든 컴파일러로 경고가 발행됩니다. 그에 대해, Javadoc 의 `@deprecated` 태그를 사용했을 경우는, 모든 컴파일러로 그 태그에 근거해 경고가 발행된다고는 할 수 없습니다. 현행의 Sun 의 컴파일러에서는, 이 태그가 사용되고 있는 경우에서도 경고는 발행됩니다만, 다른 컴파일러에서는 경고가 발행되지 않는 경우도 있습니다. 따라서,`@Deprecated` 주석을 사용해 경고를 생성하면, Javadoc 의 `@deprecated` 태그에 의존하는 것보다, 이식성이 높아집니다.

게다가@Deprecated 주석을 사용하면, 프로그램 요소가 표시되는 장소에 관계없이, javadoc 에 의해 생성된 문서에 「Deprecated」마크가 뒤따릅니다.

주: 비추천은 클래스나 개개의 메소드 또는 프롭퍼티에 적용되는 것이며, 그러한 프로그램 요소의 이름에 적용되는 것이 아닙니다. 1 개의 메소드가, 비추천과 「비추천이 아니다」overload의 양쪽 모두를 가지는 일도 가능합니다. 또, 「비추천이 아니다」프롭퍼티가 비추천 멤버를 숨기거나 오버라이드(override) 하는 것으로써, 비추천을 제외하는 일도 가능합니다. 어느 메소드를 비추천으로 할 필요가 있는 경우, 그 메소드의 오버라이드(override)를 비추천으로 하는 것은 API 의 개발자의 책임입니다.

#### 례

다음에 나타내는 것은 @Deprecated 주석의 간단한 사용예로,`java.lang.Thread` 로부터의 발췌입니다.

    public
    class Thread implements Runnable {
    ...
    @Deprecated
        public final void stop() {
      synchronized (this) {
    ...

### @deprecated Javadoc 태그의 사용

`@deprecated` 태그를 사용하면(자), Javdoc 에 의해, 어느 프로그램 요소가 비추천인 것을 명기시킬 수가 있습니다. `@deprecated` 태그의 뒤에는 스페이스 또는 개행을 둘 필요가 있습니다. ``@deprecated` 태그에 계속되는 단락에서는, 그 항목이 비추천이 된 이유와 그 대신에 사용해야 할 항목에 대해 설명합니다.`

JavaDoc 는,`@deprecated` 태그에 근거해, 특별한 HTML 를 생성합니다. 우선,`@deprecated` 태그에 계속되는 단락을 설명전으로 이동해 이탤릭체로 표시해, 그 직전에 「주: foo 는 추천 되지 않습니다.」라고 하는 경고를 굵은 글씨로 표시합니다. Javadoc 는 또, 비추천 항목을 나타내는 인덱스의 엔트리에 대해서 「추천 되지 않습니다.」라고 굵은 글씨로 표시합니다.

」라고 굵은 글씨로 표시합니다. 이 태그를 붙인 단락에 아무것도 기술하지 않는 것도 가능합니다만, 비추천을 나타내는 단락을 공백으로 하는 것은 바람직하지는 않습니다. 아무것도 기술되어 있지 않으면 비추천의 기능을 사용했을 경우에 발행되는 경고에 사용자가 대처할 수 없기 때문입니다. 또, 같은 기능을 갖춘 신버젼을 참조하는 `@link` 태그 또는 `@see` 태그를 단락에 포함하도록 해 주세요. 비추천 API 의 단계적 폐지의 예정 기일을 구체적으로 설명하는 것은 적절하지는 않습니다.

Javadoc 의 `@deprecated` 태그의 사용 방법의 자세한 것은,「javadoc - Java API 문서 제네레이터」라고 「Javadoc 툴용 다큐멘테이션 코멘트의 기술 방법」을 참조해 주세요.

#### 례

이후에의 예는 각각,`@deprecated` Javadoc 태그의 사용 방법을 나타내고 있습니다. 또,`@Deprecated` 주석의 사용예도 포함되어 있어 이 2 개(살)을 함께 사용해야 하는 것인 것을 강조하고 있습니다.

다음의 예는, 비추천 메소드의 가장 일반적인 기술 방법입니다 (Javadoc 1.2 이후의 경우).

    /**
     * @deprecated  As of release 1.3, replaced by {@link #getPreferredSize()}
     */
    @Deprecated public Dimension preferredSize() {
    return getPreferredSize();
    }

@link 태그에 의해 그 치환을 사용자에게 명시하고 있기 때문입니다. 다음에 나타내는 예에서는, 메소드의 취소를 행하고 있습니다.

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