JavaDocで非推奨か否か？

11

JavaDocには次のX509Certificate getSubjectDN()ように記載されています。

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

もう使用すべきではないがDenigratedではないメソッドのDeprecatedに慣れています。コメントで閉じられたこの特定のケースに関するバグレポートを見つけました：

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

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

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

java terminology javadocs

— ジェイコブ・ショーン
ソース

2

ワオ。私は答えを読みましたが、技術的には正しいと確信していますが、「否定」はひどい言葉です。彼らは単に「ディスコウレージド」を使用するべきでした。コードを吐き出す必要はありません。警告で十分です。

— エリックキング

@Eric Kingちょっと同じように感じました。私はそれが落胆するならそれを単に非難するという線に沿ってもっと考えていました。

— ジェイコブシェーン

9

Merriam-Websterのdenigrateの定義は以下を示唆しています：

1：名声を攻撃する：名誉 < 損 <相手
を否定する> 2：重要性または有効性を否定する：ベリトル <成果を否定する>

関連する別のバグで書かれた内容に基づいて、名誉/ 損/ベリトルはjavadocsで使用される表現の意図と一致するようです- バグID：4959744 Denigrate X509Certificate.getSubjectDN（）＆co：

X509CRLでのX509CertificateとgetIssuerDNにおける方法はgetSubjectDN（）とgetIssuerDN（）（）問題があります。これらは、非常に緩やかな仕様を持つjava.security.Principalインターフェースを実装する不特定のクラスを返します。

getSubjectDN（）およびgetIssuerDN（）メソッドには追加の仕様が存在しないため、実装が任意の実装固有のクラスを返すことは許可されています。現実の世界の経験では、これはコードの非移植性または非信頼性をもたらすケースであることが示されています。互換性の理由から、これらのメソッドの仕様は変更できず、それらは救済不能と見なされる必要があります。

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

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

評価

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

バグID 5008142を読んだことで、この「無視された」ものについて混乱しているという事実は、それを処理した開発者のせいに見えます。

彼らは、バグ4959744を見つけて、評価でそれを参照する必要がありました。あいまいな声明ではなく、「深刻な場合にのみ使用されるべきです」。「バグID 4959744による中傷を支持して非推奨が検討され、評価され、拒否された」などの正当化により、おそらく重複として閉じることさえできます。

少なくとも、彼らはバグトラッカーの関連レポートフィールド（以前のbugs.sun.com iircで参照）でバグID 4959744（おそらく4638294と一緒に）を参照できました。これが行われていないということは、関連する問題をまったく検索しなかったのではないかと疑う人がいます。

— ぶよ
ソース

1

@FrustratedWithFormsDesignerの最も難しかった部分は、結果が「bugs.sun.com」にフィルターされるように、Oracle検索ページで「denigrated」と入力する方法を理解することでした。残りは簡単で、ポップアップした検索結果をいくつか確認しました。「侮辱」は:)検索するかなり良いの言葉です

— ブヨ

1

私がGoogleを使って最初の1つを見つけたが、他の人には与えられなかったのを見てください。私はおそらくもっと厳しく見えるべきだった。ありがとう

— ジェイコブシェーン

@jschoenこれはあなたのせいではないでしょう。私はその答えを拡大しました

— -gnat

4

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

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

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

ある時点で、この種のアドバイスは、javadocタグと注釈の組み合わせに基づいて、これらのそれほど有害ではないAPI要素を使用するためのプログラムによるチェックを可能にする、非推奨の「廃止」機能で正式化されるかもしれません。

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

— ジェイコブ・ショーン
ソース