いつ、どのように API を非推奨とするか (John Rose によるドキュメントに基づく) 管理者 doug.kramer@sun.com

非推奨 API に関する ホームページ

目次

• 「非推奨」の意味すること
• いつ非推奨とするか
• 非推奨とされた API はどうなるか
• 非推奨とする方法

「非推奨」の意味すること

「自分でも推奨できないユーモア」という言葉を聞いたことがあるかもしれません。これは、話し手の重要性を著しく低下させるようなユーモアのことです。非推奨のマークの付いたクラスやメソッドもそれと同様で、重要性が著しく低下しています。つまり、そのクラスやメソッドの重要性は「非常に」低く、将来は存在しなくなる可能性が高いため、今後一切使用すべきでないことを意味しています。

非推奨が必要なのは、クラスが発展するにつれてその API も変化するためです。メソッドは一貫性を保つために名前が変更されます。より適切なメソッドが新たに追加されます。属性は変化します。しかし、このような変化は問題も引き起こします。ユーザが新しい API に移行するまでは従来の API を維持する必要がありますが、開発者たちが従来の API を使ってプログラミングを行わないようにもしなければなりません。

クラスやメソッドに「非推奨」のマークを付けることにより、この問題を解決することができます。従来の API を使用する既存のクラスは引き続き機能しますが、コンパイラは非推奨項目への参照を発見すると警告を発行します。しばらくの間、API コメントは、非推奨項目を使用するユーザに対し警告を発行し、使用を回避する方法を伝えます。@deprecated タグは上記の役割を果たしています。

注: 「deprecated (非推奨の)」と「depreciated (切り下げられた)」は同義ではありません。「depreciated」は金融・財政用語で、「切り下げ」を意味します。意味が似ているとはいえ、クラスやメソッドは「非推奨とされる (deprecated)」のであり、「切り下げられる (depreciated)」のではありません。

いつ非推奨とするか

新しい API の設計者は、それらが従来の API に置き換わるものであるかどうかを注意深く検討する必要があります。新しい API が従来の API と置き換わるものであり、ユーザに対して以前の API から新しい API への移行を勧める場合は、ドキュメンテーションコメントに非推奨に関する段落を追加する必要があります。非推奨を示す段落に何も記述されていない、ということがないように注意してください。何も記述されていないと、非推奨機能を使用した場合に発行される警告にユーザが対処できません。

ユーザに対して、新しい API への乗り換えを勧める有効な理由は、次のとおりです。

 - 旧来の API は不安定で、バグがあるか、非常に非効率的である
 - 旧来の API は将来のリリースで廃止される
 - 旧来の API を使用すると、不適切な手法でコーディングを行うようになる

これらの理由は、すべて同等の重要性を持つものではありませんが、どの場合も (使用を禁止しないまでも) 非推奨とする十分な根拠があります。非推奨 API の使用により、デフォルトでハードエラーが発生することはありません。また、ユーザがいつ新しい API へ移行したらよいかを決めるための補助として、非推奨の技術的理由をコメントに簡潔に含めることも必要です。

非推奨とされた API はどうなるか

クラスやメンバのアクセス検査ロジックと平行して、コンパイラはアクセスするクラスやメンバの「非推奨」属性を探し、推奨されないクラスやメンバが使用されている場合には警告を発行します。

注: 非推奨を含むコンパイルユニットが、非推奨クラスまたはメンバを使用するコンパイルユニットとともにコンパイルされる場合、非推奨に関する警告が抑制されてしまいます。このため、警告が発行されることなく、古い API が組み込まれてしまいます。現在のところ、これ以外の理由で非推奨に関する警告が抑制されることはありません。

Javadoc では、html ファイル生成時の @deprecated タグにも特別の注意を払っています。Javadoc は @deprecated タグに続く段落全体を解析し、それを記述部の先頭にイタリック体で表示し、その直前に「注: foo は推奨されません。」という警告を太字で表示します。Javadoc はまた、非推奨項目を示すインデックスのエントリに対して「推奨されません。」と太字で表示します。

非推奨とする方法

クラスやメソッドを非推奨にするには、Javadoc でのドキュメンテーションコメントの記述方法で説明されているように、@deprecated タグを使います。@deprecated タグに続く段落には、その項目が推奨されない理由、およびその使用を避ける方法を説明します。

非推奨クラス内の各メンバについては、プログラマがあるメンバについて特定の情報を提供したいと思うのでなければ、非推奨タグを付ける必要はありません。

注: 非推奨属性はクラスや個々のメンバに適用されるもので、名前に対して適用されるものではないことに注意してください。1 つのメソッドが、非推奨と「非推奨でない」オーバーロードの両方を持つことも可能です。また、「非推奨でない」メンバが非推奨メンバを隠すまたはオーバーライドすることにより、非推奨メンバを削除することも可能です。あるメソッドを非推奨にする必要がある場合、そのメソッドのオーバーライドを無効にすることはプログラマの責任です。

非推奨 API の段階的廃止の予定日時を具体的に説明するのは適切ではありません。これは、他の方法で伝達すべきビジネス上の決定だからです。

ある機能を非推奨とした場合、エンジニアリングを行う組織に対してその情報を伝えるのは良いことです。そうすれば、他の技術者たちも (賛否どちらの場合であっても) その変更に応じて時宜にかなった仕方で対応できます。