web-dev-qa-db-ja.com

プライベートメソッドをコピーして貼り付ける場合、Javadocを持ち運ぶ必要がありますか？

ですから、残念ながら、私はこれを行っているコードで立ち往生しています：

@Override
method A{
    //calls private methods 1-8
}

private method 1{
    //copy/pasted
}

など、すべてのプライベートメソッドについても同様です。オーバーライドしているメソッドの開発者がプライベートメソッドを保護していた方がよかったのですが、今は変更できません。

これらのプライベートメソッドにはすべてjavadocが付属しています。これをクラスのコピー/貼り付け関数と一緒に持ち運び、それに応じて調整する必要がありますか、それとも元のファイルに記載されているので時間を無駄にしないでください。

javajavadocs
1
Mitch

Javadocをメソッドと一緒にコピーすることをお勧めします。将来このクラスを見ている人は、これらのプライベートメソッドが元のクラスのメソッドとまったく同じであることに気付かない可能性があるからです。

また、新しいクラスのjavadocが生成されると、それらのメソッドには意図したドキュメントがありません。さらに、元のメソッドまたはコピーされたメソッドのいずれかの実装が個別に変更された場合はどうなりますか？ javadocが同期しなくなるのは非常に簡単です。

最後に、メソッドを大規模にコピーしているだけなので、隣接するドキュメントを同時にコピーすることは実際には時間の無駄ではありません。

2
eldon111

コードを書くときにスーパークラスからすべてのメソッドをコピーして貼り付けるわけではないのと同じように、オーバーライドされたメソッドを文書化するときにすべてのドキュメントをコピーして貼り付けないでください。

javadoc docs.Oracle.comから：

{@inheritDoc}

" nearest "継承可能なクラスまたは実装可能なインターフェイスからこのタグの場所にある現在のドキュメントコメントにドキュメントを継承（コピー）します。これにより、継承ツリーの上位に、より一般的なコメントを書き込んだり、コピーしたテキストの周囲に書き込んだりすることができます。

このタグは、ドキュメントコメントの次の場所でのみ有効です。

  • メソッドのメインの説明ブロック。この場合、メインの説明は、階層の上位のクラスまたはインターフェイスからコピーされます。
  • メソッドの@return、@param、および@throwsタグのテキスト引数。この場合、タグテキストは対応するタグから階層の上位にコピーされます。

継承階層でコメントがどのように検出されるかについてのより正確な説明については、 メソッドコメントの自動コピー を参照してください。このタグが欠落している場合、コメントはそのセクションで説明されているルールに従って自動的に継承されるかどうかに注意してください。

したがって、スーパークラスからドキュメントを継承します。スーパークラスのドキュメントが更新されると、あなたのドキュメントも更新されます。

コードの継承と同様に、コメントを拡張できます。

IDEおよびコード..でどのように見えるかを見てみましょう。

public interface IFace {
    /**
     * This is a method.
     */
    public void method1();

    /**
     * This is also a method
     */
    public void method2();
}

これは、いくつかのjavadocと2つのメソッドとの単なるインターフェースです。

クラスにこれを実装させましょう...

public class CClass implements IFace {

    /**
     * {@inheritDoc}
     * This just returns.
     */
    public void method1() {
    }

    public void method2() {
    }
}

そして、javadoc自体：

public void method1()
This is a method. This just returns.
Specified by:
method1 in interface IFace

img

public void method2()
Description copied from interface: IFace This is also a method
Specified by:
method2 in interface IFace

img

最初に確認するのは、method1を使用すると、javadocが{@inheritdoc}で含まれ、拡張されることです。ただし、nojavadocは、どこからでもjavadocを継承します。

Javadocを変更しない場合は、指定しないでください。 IDEに任せてください。javadocの自動生成にも任せてください。ドキュメントのコピーと貼り付けは、コードのコピーと貼り付けと同じくらい悪い場合がありますが、DRYそして、スーパークラスまたはインターフェースからのドキュメントがメソッドのドキュメントと同期しなくなる可能性があります。

一方、もっと何かを書くつもりなら、ドキュメントを継承して書いてください。

0
user40980

コピーして貼り付ける代わりに、ビルドの一部としてコードにパッチを適用できますか？コピーしたセクションの開始と終了を特定のコメントスタイルでマークアップし、コンパイルの前にスクリプトでそれを他のファイルにプルした場合、同じ結果が得られますが、プロセスは自動化されます。

これは明らかに一般的にひどい解決策ですが、コピー貼り付けと比較すると、少なくとも同じコードが複数の場所に吹き飛ばされることはなく、将来的に問題が発生することはほぼ確実です。

また、横方向に考えることでこれを完全に回避できる方法がないかどうかについても、非常によく考えてください。それは不可能かもしれませんが、時には賢い解決策が現れるでしょう。

0
glenatron

このような質問の場合、「私と私の組織にとってコードを理解しやすくするものは何ですか？」という質問に答えることから始めます。これが最も重要な考慮事項です。

0
Bryan Oakley