のJavaコメント

Question

私の質問は、私は次のようにコメントしなければならないされています

/** 
    * Getter for {@link #auto_key} 
    * @return {@link #auto_key} 
    */ 
    public String getAuto_key() { 
     return auto_key; 
    } 
    /** 
    * Setter for {@link #auto_key} 
    * @param auto_key the {@link #auto_key} to set 
    */ 
    public void setAuto_key(String auto_key) { 
     this.auto_key = auto_key; 
    } 

基本的に私はgetterメソッドとsetterメソッドのコメントに{@link}を使用して、聞きたいが正しいのですか？ {@link}を使わずに普通のコメントを使用する必要がありますか？ この方法はJava標準ですか、そうではありませんか？

Answer 1

慣例事項。組織を組織に変更します。以前はゲッターやセッターについては、それが何であるかが明らかである限り、コメントを気にする必要はありませんでした。 {@link}のないコメントと同じです。

現在のところ、先に書かれたコードがすでにこの規約を持っているため、{@link}を追加します。

Answer 2

実際には、私は意図的にjavadocゲッターやセッターをしません。なぜなら、これを行うことによって値を追加していないからです。彼らはアクセサーメソッドです。実際には、javadocを追加することで一種のコードを作成することになります。

私はゲッター以外の/セッターにのみjavadocを配置します。

Answer 3

に{@link}を使用すると、変数がパブリックにアクセス可能であることを意味します（そうでない場合、リンクはjavadocで解決されません）。これはゲッタとセッタが冗長であることを意味します。

auto_keyフィールドを非公開にして、ゲッターとセッターを保持することを強くお勧めします。ゲッターとセッターの名前をJava規則（autoKey、setAutoKey、getAutoKey）に合わせて調整します。 autoKeyが変更された場合（ゲッター/セッターの組み合わせが一般的に示唆するように、JavaBeansを参照）、PropertyChangeEvent秒を発射することを検討してください。

ドキュメントについては、既に提案されているメソッドの名前に何も追加されていません。だから私はそれを削除するか、null、...に設定されるかもしれないかどうか、autoKeyが正確に何をするか（それはスニペットから私にはわかりません）に関するいくつかの追加のドキュメントを追加します。私はあなたのセットのためのスタンドアロンのドキュメントを生成することをお勧め

Answer 4

1. は/まだ{@link}を使用しながら、メソッドを取得し、それは両方を行うことです。この方法では、フィールドがアクセス可能な場合、人々は引き続きそのドキュメントにアクセスできます。後でそれがリファクタリングのためにプライベートになると、変更する必要のある不完全なJavadocが残ってしまうことはありません。

2. セッター/ゲッターメソッドのドキュメンテーションはコードの膨張のように見えるかもしれませんが、私はまだ理由のカップルのためにそれを作成することをお勧め：

   • それは重要な情報を言及するあなたの標準的な場所を提供しますが、のようなsetterの引数は、nullであってはいけません。また、インタフェースの特定の実装で悲惨に非効率的なgetterであってはなりません。

   • リーダーが自動的にバッキングフィールドの内容を認識しているとは限りません。確かに、setLength()はいくつかの文脈で十分に記述的かもしれませんが、正確にはsetLimit()は何をしますか？

   • はバッキングフィールドであるとは限りません。また、get/setメソッドは特定の実装でのみ行われます。リファクタリングが互換性の問題によって制限されると、さまざまなアーティファクトが残されるというのは不幸な現実です。例えば。 setLimit()はsetSizeLimit()に委任することができますが、これは特に注意する必要があります。

   • すべてのあいまいさを削除します。あなたが常識であると考えるものは、すべての人々にとって単純ではないかもしれません。ドキュメンテーションがなければ、真実かもしれないし、そうでないかもしれない様々な仮定がなされるだろう。たとえば、リストの実装では、setLength(0)も含まれているすべての参照をnullに設定していますか？

   • 最も重要な点は、Javadocポリシーが単純な「すべての文書をすべて文書化」するということです。一方、様々な例外を含むポリシーを持つことは必然的に、文書化されずに残された怠惰とコードに必然的につながります。

Answer 5

あなたは、この方法は1のように見えていない限り、ゲッターやセッターを記述した任意のコメントを置くが、異なる振る舞いをカプセル化してはいけません。