Javaで開発中としてクラスにフラグを付ける方法

私はインターンシッププロジェクトに取り組んでいますが、すべてを終える前に辞めなければなりません。

実稼働で使用するには十分に安定していないクラスが1つあります。このクラスをマーク/フラグ付けして、他の人が実稼働で誤って使用しないようにします。私はすでにJavadocに通知を出しましたが、それでは十分ではないようです。コンパイラーのエラーまたは警告の方が良いでしょう。

コードは次のように構成されています。

[Package] | company.foo.bar.myproject
          |-- Class1.java
          |-- Class2.java
          |-- Class3.java <--(not stable)

パブリックメソッドでこれらのクラスを呼び出す単一のファクトリクラスがある場合、メソッドをclass3asに設定できますprivate。ただし、APIはそのようには公開されません。ユーザーはこれらのクラスを直接使用します。たとえばnew Class1();、トップレベルのクラスをプライベートにすることはできません。この状況に対処するためのベストプラクティスは何ですか？

なぜすべての不安定なクラスをバージョン管理システム上の別のブランチにチェックインしないのですか？

クラスに適切にコメントを付けた場合、不完全な機能の一部を「非推奨」としてマークしたり、メソッドの内部をコメントアウトしてを挿入したりできますthrow new UnsupportedOperationException();。

参照は、Javaで、.NETのNotImplementedExceptionのようなものはありますか？詳細については。

このようなコンパイラの警告は知りません。

あなたの状況では、おそらく@Deprecated注釈を使用します。メソッド呼び出しを取り消すので、何かが起きていることが他の人に明らかになります。彼らが最新情報を見ると、「生産準備ができていません」というコメントが表示され、AHAが表示されます。

私は標準としてコードをマークする方法があるとは思わないWIP、Incompleteまたはそのような何かが。

という名前の新しい例外を作成ClassUnstableExceptionし、Class3コンストラクタで例外を発生させて、例外の使用方法を説明するメッセージを出すことができます。ただし、実行時に警告するだけなので、これは悪いことです。

あなたはまた、いくつかの方法でクラスincompilableを作ってみてください、その後、誰かがコードを修正するために行く場合は、彼らがするようにコンパイラをトリップコードのセクションにメモを追加することができ、うまくいけばの説明を参照なぜ、彼らはそのクラスを使うべきではありませんが。一部のIDEにある半自動化された「この問題を修正」ツールを使用している場合、これは機能しない可能性があります。また、ビルドが壊れる可能性があるため、これも悪いです。

という名前の注釈を作成してWIP（私が考えることができる最も近いものですDeprecatedが、実際には同じことを意味しないため）、それを使用してクラスに注釈を付けることができます。これはおそらくもう少し手間がかかりますが、注釈をサポートするものは何でしょうか？

最後に、コメントに追加することもできますが、実際に読んだ場合にのみ機能します。

編集：

これは関連する可能性があります：意図的にカスタムJavaコンパイラの警告メッセージを発生させる方法は？

コンパイル時の注釈処理を導入できますが、これによりチームのすべてのメンバーがコンパイルプロセスを調整するように強制されます。

しかし、プロセス全体が少し混乱します。不安定なAPIは、バージョン管理システムにブランチを作成して明確に分離する必要があります。それが本当にコードベースの残りになければならない場合、不安定であると文書化されていますが、それでも慣れるのは問題は本当に技術的ではなく、組織とコミュニケーションにあります。はい、技術的な検証（注釈処理など）を導入することはできますが、それでも問題は解決しません。別のレベルに移動するだけです。

だから私の推奨事項は次のとおりです。異なるブランチにコードベースを配置してコードベースを分離できない場合 、人々と話し、なぜ彼らがAPIを使用してはならないのかを説明してください。

そもそもなぜそこにあるのですか？

不安定なコードをメインラインにチェックインしましたか？どうして？

不安定なコードは、trunk / main / masterなどのメイントランク名にはチェックインしないでください。これはリスクの高い開発であると見なされ、代わりに、メインにチェックインするのではなく、作業した独自のブランチで隔離する必要があります。

高度なSCM分岐戦略を読むことを強くお勧めします。特に、開発の役割と、リスクの高い開発と見なされるものについての説明に注意してください。

一般に、リスクの高いプロジェクトごとに別々のブランチを使用することを検討してください。高リスクプロジェクトは、大規模、多数の人々、なじみのない主題、高度に技術的な主題、非常に厳しいスケジュール、不確実な納期、不完全または不安定な要件、および地理的に分散したプロジェクトチームによって特徴付けられます。同様に、各リリースで低リスク開発のために単一のブランチを指定することを検討してください。[WING98]を含むいくつかのソースは、この目的のためにメインラインを使用することを推奨しています。この一連の行動に取り組む前に、メインラインについて上記で検討した要因を考慮してください。製品ファミリの複数のメンバーがメインラインを通じて調整している場合でも、低リスク開発はメインラインとは異なるポリシーを持つ場合があります。

不安定な（または未使用の）コードをメインラインにチェックインさせることは、このコードを維持しようとする将来の開発努力を混乱させることを意味します。誰かの「死んだcodE」と言って削除するまで、今から終わりまでのすべてのブランチと担当者のクローンにはこれが含まれます。

「まあ、ブランチで忘れられた」と言う人もいますが、それは真実かもしれませんが、メインラインで死んだ（そして不安定な）コードを忘れると、それが削除されるまで将来のすべての開発を混乱させるため、何倍も悪化します-そしてそれはさらに忘れられています。"/ fooProject / branches / WeisBigIdea"（または同等のもの）の適切な名前のブランチが表示され、将来的には（特にそれが機能する場合）作業が容易になります。

@Deprecated

最初のことは@Deprecated注釈です。これはjavadocを超えて、コンパイラの警告を吐き出します。javac次の-deprecationように説明されるフラグを提供します。

非推奨のメンバーまたはクラスの各使用またはオーバーライドの説明を表示します。なければ-deprecation、javacショーのソースファイルの要約は、使用またはオーバーライドは、メンバーやクラスを非推奨のこと。-deprecationはの省略形です-Xlint:deprecation。

前述のように、これは標準のコンパイラ警告を超えています。

多くのIDEでは、廃止されたメソッドと値は取り消し線付きで表示されます。

foo.bar();

そして、次のような出力を生成します：

$ javac -Xlint:all Foo.java Bar.java
Bar.java:2: warning: [deprecation] Foo in unnamed package has been deprecated
interface Bar extends Foo { }
                      ^

ビルド構造によっては、ビルドが壊れる可能性があります。これは、クラスの1つが使用された場合にのみビルドを中断します（単にコンパイルされるだけではありません）。

@CustomAnnotation

これには多くのアプローチがあります。たとえば、Lightweight javac @Warningアノテーションは、そのアノテーション付きの何かが使用されるとコンパイル時に警告を発するアノテーションプロセッサを提供します（カスタムアノテーションプロセッサに関するnetbeansチュートリアル、背後で何が起こっているのかを知ることができます）シーン）。

オラクルは、Javaのメタデータを@Unfinished最大限に活用する、パート2：カスタムアノテーションで、アノテーションにカスタムアノテーションを使用する例を説明しています。。

AnnotationProcessor、あなたはコンパイル時に任意のコードを実行することができます。何をしたいかを決めるのはあなた次第です。警告、何かが使用されている場合はビルドを中断します。この種のコードを作成する方法については、Web上に多数のチュートリアルがあります。コンパイル時にエラーを生成するか（これは迷惑で、削除されることになります）、または使用する場合は（作成するのがやや複雑になります）。

これはすべて、実際に注釈プロセッサを使用するようにビルドを変更することを意味することに注意してください。

すべての不完全なクラスを、「NOTCOMPLETE」のような明白な名前のサブパッケージに移動できますか？それはちょっとしたハックですが、十分に見えるかもしれません。

（それらがすべて同じパッケージにない場合は、その下にパッケージ構造を再作成できます。）

コード内でこれを行うための本当に良い方法があることは知りません。下がってください：

プロジェクト全体の2つのコピーを作成します。1つはクラスあり、もう1つはクラスなしです。クラスを含まないバージョンを安定したコードベースとしてマークし、本番リリースの準備ができている、およびクラスを含むバージョンを将来のリリースの開発としてマークします。このクラスを生産品質と見なす前に何が必要かを文書化します。

理想的には、選択したソース管理ソリューションのブランチを使用してこれを行う必要があります。あなたはそのような分岐戦略を使用していないように聞こえるので、しかしあなたは少しチートする必要があるかもしれません。新しいクラスを慎重に削除し、新しいクラスをチェックインし、回帰テストを行います。安定していることが確認できたら、そのリビジョンにタグを付け、タグから開発ブランチを作成してから、開発ブランチにクラスを追加し直すことができます。

クラスを抽象化し、適切にコメントすることを選択します-そのように、コードは参照のためにまだありますが、それをインスタンス化しようとする人には幸運です:)

コンパイラが解決できない依存関係を作成するのはどうですか？追加するだけです：

import this.is.not.done.yet.do.not.use.it;

頂点に。ユーザーはそれを使用してコンパイルできません。

クラスをテストする場合は、その名前でパッケージ/クラスを作成するだけで（または「experimental.danger」のような単純なものを使用して）、新しいコードをテストできます。