web-dev-qa-db-ja.com

JavaDocでの非推奨と非推奨？

_X509Certificate_ getSubjectDN() のJavaDocでは、

Denigrated、getSubjectX500Principal（）に置き換えられました。

私は、もはや使用されるべきではないが非難されるべきではないメソッドのために、Deprecatedを使用することに慣れています。コメントでクローズされたこの特定のケースについて バグレポート が見つかりました：

これはバグではありません。 「非推奨」は、深刻なケースでのみ使用されることを意図しています。

Deprecatedであるメソッドを使用している場合、一般的に推奨されるアクションは、メソッドの使用を停止することです。

では、メソッドがDenigratedとマークされている場合に推奨されるアクションは何ですか？

javaterminologyjavadocs
11
Jacob Schoen

Merriam-Websterの denigrate の定義は、次のことを示唆しています。

1：次の評判を攻撃する： defame <相手を否定する>
2：次の重要性または妥当性を否定する： belittle <成果を否定する>

別の関連するバグの記述に基づいて、defame/belittleは、javadocsで使用されている表現の意図と一致しているようです- Bug ID：4959744 Denigrate X509Certificate.getSubjectDN（） ＆co ：

X509CertificateのメソッドgetSubjectDN（）およびgetIssuerDN（）とX509CRLのgetIssuerDN（）には問題があります。それらは、非常に緩やかな仕様を持つJava.security.Principalインターフェースを実装する未指定のクラスを返します。

GetSubjectDN（）およびgetIssuerDN（）メソッドには追加の仕様がないため、実装が任意の実装固有のクラスを返すことは許容されます。実際の経験では、これがコードの移植性や信頼性の低下につながるケースであることが示されています。互換性の理由から、これらのメソッドの仕様は変更できず、それらは回収できないと見なす必要があります。

明確に定義されたX500Principalクラスのインスタンスを返す置換メソッドgetSubjectX500Principal（）およびcoがJDK 1.4に追加されました。これらのメソッドの実装は、この種のすべての問題を回避するように設計されています。ただし、新しいメソッドは露出不足の影響を受け、プログラマーは使い慣れた、より直感的な名前のgetSubjectDN（）およびcoメソッドを引き続き使用します。

これを変更するには、古いgetSubjectDN（）およびgetIssuerDN（）メソッドを廃止する必要があります。これにより、このメソッドを使用する開発者がコンパイル時の警告を受け取ることが保証されます。

評価

...この場合、廃止は不適切と見なされました。代わりに、注意コメントがJavaDocに追加されました。

Bug ID 5008142を読んだことで、この「問題のある」ものについて混乱しているという事実は、それを扱った開発者の過失のように見えます。

彼らは、バグ4959744を見つけて、評価でそれを参照するべきでしたが、「深刻な場合にのみ使用することを意味する」という曖昧なステートメントではありません。 「バグID 4959744による否定を支持して、廃止が検討、評価、拒否されました」のように正当化することで、おそらく重複する可能性もあります。

少なくとも、Related Reportsフィールド（と呼ばれる）でバグID 4959744（多分 4638294 と一緒に）を参照できますバグ追跡システムの古いバグ（Sun.com iirc）のも参照してください。これが行われていないことは、関連する問題をまったく検索しなかった疑いを抱かせます。

9
gnat

さらに掘り下げた後、 JDKでの非推奨 というブログ投稿を見つけることができました。基本的に、Deprecatedとマークされているものは使用すると有害であると見なされ、単に推奨されないものがあることを示しています。

いくつかの機能リリースの一般的なポリシーでは、コアJDKコンポーネントは、有害である場合にのみ非推奨としてマークされます。クラスまたはメソッドの使用が不適切な場合、通常は非推奨のマークを獲得するには不十分です。

彼は現在、使用をやめさせるようにアイテムをマークする方法はあるが、最終的にこれを行う方法を追加するかもしれないと述べました。

ある時点で、この種のアドバイスは、javadocタグとアノテーションの組み合わせに基づいた、害の少ない非推奨の「拒否」機能で形式化され、これらの害の少ないAPI要素の使用をプログラムでチェックできるようになります。

Denigratedという用語を使用する決定について、他に何も見つけることができませんが、これはかなり近いようです。そしてこれに基づいて、開発者が取るべきアクションはDeprecatedと同じであるようです。このメソッドは使用しないでください。

4
Jacob Schoen