@deprecated 태그 - xrath.com 에서 번역됨

비추천 API 에 관한 홈 페이지

# @deprecated 태그

"@deprecated":폐지가 결정된 API 에 관한 정보의 제공

John R. Rose
1996 년 10 월 4 일

문제 -

Java 1.1 에서는, 새로운 API 가 많이 도입되었습니다. 그 중에는, 이전의 API 와 옮겨지는 것도 있었습니다. 신구의 API 가, 같은 패키지내에 공존하고 있는 것도 있습니다. 새로운 API 가 이전의 API 에 옮겨지는 경우, 여러가지 면에서 프로그래머의 작업은 곤란하게 됩니다만, 대부분의 경우는, 그러한 API 를 무시할까 사용하지 않게 하는 것으로 대처할 수 있습니다.

부분적인 해결책:이전의 클래스, 메소드, 및 필드가 새로운 버젼에 의해 옮겨놓을 수 있었을 경우, 이전의 버젼에 「비추천 (deprecated)」이라고 하는 마크를 붙일 수 있고 있으면, 프로그래머는 중요한 부분에 주의를 집중시킬 수가 있게 됩니다. 같이 비추천의 API 가 사용되고 있는 경우에, 컴파일러가 프로그래머의 주의를 환기하는 것으로써, 프로그래머의 부담을 가볍게 할 수가 있습니다.

상세:

다큐멘테이션 코멘트내에서, 새롭고 단락 태그 「@deprecated」를 정의했습니다 (JLS, $$184 를 참조). 이 태그는, 클래스와 멤버 다큐멘테이션 코멘트의 양쪽 모두로 표시 가능해, 특히 그 코멘트가 가리키는 구조에 적용됩니다.

태그 붙이고 된 단락은, 공백대로 해 둘 수도 있습니다. 공백으로 하지 않는 경우, 그 단락에서는, 프로그래머가 비추천의 기능의 사용을 피하는 방법을 설명할 필요가 있습니다.

「@see」태그가 붙은 단락은, 반드시 포함할 필요가 있습니다.

같은 기능을 가지는 새로운 버젼에의 참조를 나타냅니다. 컴파일러에 관한한, 다큐멘테이션 코멘트행의 최초로 (공백 문자를 제외하다) 「@deprecated」라고 하는 캐릭터 라인이 있는 경우, 대응하는 클래스, 필드, 메소드용의 클래스 파일에 「비추천」속성을 붙입니다.

게다가 클래스나 멤버의 액세스 검사 논리와 평행 해, 컴파일러는, 액세스 하는 클래스나 멤버의 「비추천」속성을 찾아, 추천 되지 않는 클래스나 멤버가 사용되고 있는 경우에는 경고를 발행합니다.

비추천 속성은, 클래스나 개개의 멤버에게 적용되어서 , 이름에 대해서 적용되는 것은 아닌 것에 주의해 주세요. 1 개의 메소드가, 비추천과 「비추천이 아니다」overload의 양쪽 모두를 가지는 일도 가능합니다. 또, 「비추천이 아니다」멤버가 비추천 멤버를 숨기는 또는 오버라이드(override) 하는 것으로써, 비추천 멤버를 삭제하는 일도 가능합니다. 어느 메소드를 비추천으로 할 필요가 있는 경우, 그 메소드의 오버라이드(override)를 무효로 하는 것은 프로그래머의 책임입니다.

비추천을 포함한 컴파일 유니트가, 비추천 클래스 또는 멤버를 사용하는 컴파일 유니트와 함께 컴파일 되는 경우, 비추천에 관한 경고가 억제되어 버립니다. 이 때문에, 경고가 발행되는 일 없이, 낡은 API 가 짜넣어져 버립니다. 현재로서는, 이외의 이유로써 비추천에 관한 경고가 억제될 것은 없습니다.

가상적인 「-strict」옵션을 컴파일러에 대해서 지정하면(자), 비추천에 관한 경고를 포함한, 모든 경고를 하드 에러로 할 수 있습니다. 이것은, 새롭게 추가된 기능입니다.

Javadoc 에서는, 비추천의 단락을 강조 표시할 필요가 있습니다. 비추천의 이름에의 참조의 옆에, 고유의 기호 문자를 붙일 필요가 있는 경우도 있습니다.

예제:

무엇보다 일반적인 비추천 메소드의 예를 다음에 나타냅니다.

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

(주:「@deprecated」태그의 뒤에는 스페이스 또는 개행을 둘 필요가 있습니다. 「@see」태그는, 행의 선두에 둘 필요가 있습니다. JLS 18 장을 참조해 주세요. )

비추천이 단지 이름의 변경에 관한 것이면, 「이 메소드는 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 에 이행 하면(자) 좋은가를 결정하기 위한 보조로서 비추천의 기술적 이유를 코멘트에 간결하게 포함하는 일도 필요합니다.

(비추천 API 의 단계적 폐지의 예정 일시를 구체적으로 설명하는 것은 적절하지는 않습니다. 이것은, 다른 방법으로 전달해야 할 비지니스상의 결정이기 때문입니다.

비추천 클래스내의 각 멤버에 대해서는, 프로그래머가 있는 멤버에 대해 특정의 정보를 제공하고 싶다고 생각하므로 없으면, 비추천 태그를 붙일 필요는 없습니다.

어느 기능을 비추천으로 했을 경우, 엔지니어링을 실시하는 조직에 대해서 그 정보를 전하는 것은 좋은 일입니다. 그러면, 다른 기술자들도 (찬부 어느 쪽의 경우여도) 그 변경에 응해 적당한 시기에 필적한 방법으로 대응할 수 있습니다.

그 외의 설계 옵션:

비추천 기능은, 컴파일러가 다큐멘테이션 코멘트의 내용을 인식하게 된 최초의 사례입니다. 이전에는, 컴파일러는, 다큐멘테이션 코멘트가 구문나무 중(안)에서 적절한 위치에 있는 것을 확인하고 있었습니다만, 현재는 구현되고 있지 않습니다. 지금까지, 코멘트의 내용에 응해 컴파일러를 동작시키는 것을 경솔하게 선택할 것은 없었습니다.

코멘트의 내용을 조사하는 선례로서는, 「lint」가 있습니다. 이것은 /*PRINTFLIKE2*/ 등의 코멘트를 사용해 C 의 API 에 주석을 붙이고 있었습니다.

Java 의 다큐멘테이션 코멘트는 구조화 되고 있는 것, 및 그 구조는 Java 언어 스펙으로 규정되고 있는 것에 주의해 주세요. 이것은, 특정의 종류의 코멘트 서식은 벌써 규정되고 있어 Java 에 의한 설계는, 명확하게 차별화되어 있지 않은 lint 의 규약보다 적정인 것을 의미하고 있습니다.

프라그마를 도입해, 비추천의 지정에 사용하는 (<*deprecated*> 등) 일도 검토되었습니다만, 호환성이 없는 다수의 확장에 넓게 출입문을 여는 결과가 되어, 심각한 오용의 가능성도 있기 위해서(때문에) 각하 되었습니다.

다만, @deprecated 는 프라그마와 같은 기능을 가집니다. 즉, @deprecated 는 원시 코드내에 있어, 그 정보를 제공합니다만, 시멘틱스는 변경하지 않습니다. @deprecated 가 많은 프라그마와 다른 점은, 인간인 사용자를 대상으로 하고 있다고 하는 점입니다.

컴파일러는, 경고를 발행해, 우호적이고 유용한 조언을 제공합니다만, 규칙을 강제할 것은 없습니다. 비추천에 관한 단락의 내용을 반영할지 어떨지는 프로그래머에게 걸려 있습니다. 데이터를 주로 사용하는 것은 인간이기 (위해)때문에, 비추천 정보는 코멘트에 포함할 수 있고 있습니다.

「이행중 (transient)」와 같은 키워드를 도입하는 일도 검토되었습니다. 이것은, 문제에 기계적으로 대처하려면 도움이 됩니다만, 언어 자체를 변경해야 하게 됩니다. 특히, 이전에 예약되어 있지 않았던 식별자 ( 「var」등)를 코드로부터 없앨 필요가 생깁니다. 게다가 비추천의 주된 사용자는 인간이기 (위해)때문에, 키워드에 의존하는 방법은 비효율적으로, 코멘트 규칙을 추가해야 하게 됩니다. 코멘트 규칙은 javadoc 에 통합하는 것이 바람직할 방향입니다. 상기의 이유로써, 키워드를 사용한다고 하는 방법은 현실적이지 않다고 판단되었습니다.

종래 컴파일러는 다큐멘테이션 코멘트를 무시해 왔고, 일반적으로 무시해야 합니다. 이것에는 받아들여야 할 불규칙한 예외가 있습니다. 다만, 비추천용의 그 외의 설계 옵션에 포함되는 불규칙성은 바람직한 것으로는 없습니다.

Copyright © 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn.View, CA 94043-1100 USA.All rights reserved.