メソッドまたはAPIがコードベースにあるが、実装が完全でないか変更される可能性があるため使用しないことを意味する「非推奨」と同様であるが異なる適切な用語はありますか? (そうですね、これらのメソッドは公開すべきではありません。yadayada yada。自分の状況を作り出したのではなく、それを最大限に活用しようとしているだけです。)
人々は何を示唆していますか?実験的、不完全、他に何か?
まだ流動的なこのAPIのjavadocドキュメントを作成している場合、@ deprecatedタグを使用する必要がありますか、それともより良い規則がありますか?私にとって@deprecatedは、このAPIが古く、新しい優先メカニズムが利用可能であることを意味します。私の状況では、代替手段はありませんが、APIの一部のメソッドは完了していないため、使用しないでください。この時点では、それらを非公開にすることはできませんが、ドキュメントに明確な警告を入れたいと思います。
適切な用語はおそらくincubatorで、これはGoogleとApacheで使用されているものです。
Google Web Toolkitのウィジェットとライブラリの公式インキュベーター...
...完全に本格的なApache Software Foundationプロジェクトになることを目的としたオープンソースプロジェクトのゲートウェイ...
上記のプロジェクトをよく見ると、「実験的な」API(GWTなど)には、com.google.gwt.gen2
のような「専用の」パッケージ名が付いている傾向があります。これは、永続的な公共の消費を目的とした将来の「最終化された」APIを汚染しないようにするためです。
「ダイヤモンドのような公開APIは永久に存在します。正しく取得するチャンスが1回あるので、最善を尽くしてください...」(Joshua Bloch、- 優れたAPIを設計する方法と重要な理由 )
純粋に実用的な理由で@deprecated
を使用します。
@deprecated
は、希望する正確な意味を伝えていませんが、重要な利点があります:Javaコンパイラには組み込みのサポートがあります。-deprecation
フラグを使用したコンパイル非推奨のメソッドをオーバーライドするすべての場所を見つけることができるため、ユーザーは不審なコードをすばやく見つけることができます。@deprecated
Javadocタグを使用すると、ドキュメントを読みたい人に実際に何が起こっているのかを説明できます。 APIは試験的なものであり、自己の責任において使用する必要があることなどをユーザーに伝えることができます。
実験的な機能や不完全な機能はパブリックAPIでは何もしないため、他のAPIでこのようなものを見たことはありません。
選択肢がないため、APIの一部が変更される可能性があることを明確に示す警告を表示します。