web-dev-qa-db-ja.com

1つのjavadocコメントで同じクラスへのリンクを繰り返すことは悪い習慣ですか？

私は現在、APIとそのドキュメントを書いています。たとえば、私は次のようなものを持っています：

public interface Event {
}

public interface Process {
}

public interface EventProcessor {
    /**
     * Starts to process the sepcified event asynchronously. The returned
     * {@link Process} can be used to track progress on the processing. If the
     * specified event causes more {@link Event events} to be processed in this
     * system, then they are also tracked via the returned {@link Process}.
     * 
     * @param event
     *            to be started to process
     * @return
     */
    Process startProcessing(Event event);
}

上記の例では、インターフェイスProcessへのjavadocリンクが繰り返されています。私が書いているAPIでは、1つのjavadocコメントに同じクラスへの参照がさらにいくつかある場合があります。

クラス/メソッドなどへの参照を常にマークする必要があります。 javadocリンクとして？

一般的に、javadocコメントに多くのリンクがあることは、高い結束の兆候だと思います。しかし、リンクされている同じターゲットであることが多い場合、これが適切かどうかはわかりません。

javaprogramming-practicesdocumentationcoding-stylejavadocs
3
SpaceTrucker

Oracle javadocガイドライン の内容は次のとおりです。

インラインリンクを経済的に使用する
{@ link}タグを使用して、API名（すぐ上にリストされている）へのリンクを追加することをお勧めします。ドキュメントコメントにすべてのAPI名のリンクを追加する必要はありません。リンクは（HTMLでの色と下線、およびソースコードのドキュメントコメントでの長さによって）注意を喚起するため、大量に使用するとコメントが読みにくくなる可能性があります。したがって、次の場合はAPI名へのリンクを追加することをお勧めします。

  • ユーザーは実際にそれをクリックして（あなたの判断で）より多くの情報を得たいと思うかもしれません、そして
  • ドキュメントコメント内の各API名の最初の出現のみ（リンクを繰り返さないでください）

私たちの聴衆は上級（初心者ではない）プログラマーなので、Java.langパッケージ（Stringなど）のAPI、またはよく知られていると思われる他のAPIにリンクする必要は通常ありません。

要約すると、同じリンクターゲットへのリンクを繰り返すことは悪い習慣です。

私をそこに向けてくれた@AaronKurtzhalsに感謝します。

3
SpaceTrucker

私はあなたに言うのは嫌いですが、あなたが本当に（本当に）なら繰り返し生成されたjavadocの読者は、textが2回繰り返されるので、リンクがいくつあるかは関係ありません。

...返されたプロセス処理の進行状況を追跡するために使用できます。指定されたイベントにより、このシステムでさらに多くのイベントが処理される場合、それらもreturned Processによって追跡されます。

だから、リンクするかしないかする前に、リンクするかしないかをする前に、基本を決めた方がいい：繰り返しについて心配するか =）textかどうか？

  • テキストの繰り返しについて心配しないことにした場合は、リンクについて心配しない方が本当に理にかなっています。リンクを使いやすい方法で使用してください。繰り返されるテキストを見ている読者は、その中のリンクを提示する一貫性についてのあなたの努力を評価することはほとんどありません。

一方、テキストの繰り返しを避けるためにドキュメントを言い換えることを決定した場合、これはリンクの繰り返しに関する懸念も解決します。

ここでは注意が必要です。読みやすく、繰り返しのないテキストを作成するには、かなりの労力がかかる可能性があるためです。その場合は、他の誰かにドキュメントのレビューを依頼することを検討してください（javadocsソースとは異なって見えるため、生成されます）。

贅沢なレビュアーがいない場合は、1〜2日待って（1〜2週間の方が良い）セルフレビューを行ってから、自分でドキュメントを確認してください。別の目のように。

1
gnat