メソッドのシグニチャーのすべてのパラメーターにjavadocコメントを書き込む必要がありますか？
私のチームの開発者の1人は、メソッドのシグネチャのすべてのパラメータにjavadocコメントを記述する必要があると考えています。私はこれが必要だとは思いません、そして実際それは有害でさえあるかもしれないと思います。
まず、パラメーター名は説明的で自己文書化されている必要があると思います。パラメータの目的がすぐにわからない場合は、おそらく間違っています。ただし、パラメーターの目的が明確でない場合があることは理解しています。そのため、そうした場合は、パラメーターを説明するjavadocコメントを作成する必要があります。
しかし、私はすべてのパラメーターに対してそれをする必要はないと思います。パラメータの目的がすでに明らかである場合、javadocコメントは冗長です。自分のために追加の作業を作成しているだけです。さらに、あなたはあなたのコードを維持しなければならない人のために余分な作業を作成しています。メソッドは時間とともに変化します。コメントを維持することは、コードを維持することと同じくらい重要です。 「XはYの理由でZの理由」のようなコメントを何回見たことがありますか？人々はコメントを更新するのを忘れているので、それはいつも起こります。誤解を招くコメントは、コメントをまったく付けないよりも有害であると私は主張します。したがって、過剰コメントの危険性があります。不要なドキュメントを作成することで、自分自身と他のすべての人のためにより多くの作業を行い、誰もが自分のコードを理解するのを助けず、コードがなくなる可能性が高まります。将来のある時点での最新のコメント。
しかし、私はチームの他の開発者を尊重し、おそらく彼が正しいと私は間違っていることを受け入れます。開発者仲間に質問を送る理由は次のとおりです。EVERYパラメータに対してjavadocコメントを書くことは本当に必要ですか？ここでは、コードは私の会社の内部にあり、外部の第三者によって使用されないものとします。
Javadoc（およびMicrosoft WordではXMLDoc）アノテーションはコメントではなく、documentationです。
コメントはあなたが望むようにまばらにすることができます。コードが中程度に読みやすいと仮定すると、通常のコメントは、将来の開発者がすでに2時間にわたって凝視しているコードを理解/維持するのに役立つ単なる道標にすぎません。
documentationは、コード単位とその呼び出し元の間のcontractを表します。これはパブリックAPIの一部です。常にJavadoc/XMLdocがヘルプファイルまたはautocomplete/intellisense/code-completionポップアップに表示され、notでコードの内部を調べているが単に望んでいる人に気づかれると常に想定します。 使用独自の目的で使用します。
引数/パラメータ名は、決してわかりません。あなたはいつも考えます彼らはあなたがコードの作業に過去1日を費やしたときですが、2週間の休暇の後に戻ってみると、どれほど役に立たないかがわかります彼らは本当にです。
誤解しないでください-変数と引数には意味のある名前を選択することが重要です。しかし、それはコードの問題であり、ドキュメントの問題ではありません。 「自己文書化」という言葉を文字どおりに受け取らないでください。これは、internalのドキュメント（コメント）ではなく、externalのドキュメント（契約）のコンテキストで意味されます。
すべてをコメントするか、何もコメントしない（明らかにすべてをコメントする方がはるかに良い選択です）。ソースファイルまたは生成されたdocファイル（doxygen出力など）で直接APIを確認して、コードを使用している人について考えてください。不整合は一般に混乱を招き、ソースを掘り下げて把握するのに費やされる時間につながります理由何かがコメントされなかったため、最初にパラメータがコメントされただけで回避できたであろう無駄な時間につながります場所。
覚えておいてください：あなたにとって意味のある何かは、それがどれほど平凡だと思っていても、他の人によって完全に異なって解釈されるかもしれません（英語を読み通してコードを理解しようとするのがそれほど得意でない人について考えてください）。
とはいえ、他の開発者がすべてを文書化することの重要性を強調している場合は、同じくらい強調する（それ以上ではないにしても）を最新の状態に保つ必要があります。あなたが述べたように、古くなったコメントよりもずっと悪いことはありません（省略されたドキュメントよりも悪くはないにしても、同じくらい悪い）。
開発者のサイクルは、私たちが節約しようとしているリソースであるという仮定から始めましょう。
つまり、開発者は、自明のパラメーターと戻り値を文書化して時間を無駄にすべきではないということです。
さて、分解してみましょう。
限界コメントが本当に取るに足らないものであり、考えたり調査したりする必要がないと仮定して、すべてを文書化する場合、コストは、コメントを実際に入力してタイプミスを修正するために追加される時間です。
私たちが選んだ場合、コストは次のとおりです。
- すべてを文書化する必要があると考えるチームの他の開発者との議論を持ち、勝利する。
- 各パラメータについて、これを文書化するかどうかを決定します。
- パラメータを文書化する必要があるかどうかについて別の意見を持っている場合に、チームとのさらなる議論。
- 自明であると思われるパラメータがそうではないことが判明した場合、コードの調査と調査に時間を費やします。
したがって、私はすべてを文書化する傾向があります。欠点は明確ですが、含まれています。
とにかくJavadocを作成している場合は、「明白な」パラメーターを含めて完全に記述することもできます。それらはあなたや他の開発者にとって明白かもしれませんが、それを見ている新しい人は誰でも各パラメータの意図を知ることから利益を得るでしょう。
Javadocを適切に維持するには、開発に役立つツールを使用する必要があります。 Eclipse が思い浮かびます。もちろん、それが重要な場合は、コメントを含めて、チームの全員がコードの保守を担当するようにする必要があります。
Java API 自体が主な例であるjavadocは、コードから切り離された状態でも表示できることを忘れないでください。メソッド内のすべてのパラメーターにjavadocを含めないことにより、メソッドとその使用方法を誤って表していることになります。
「必要」は完全に主観的です。私はあなたが求めているのは、「あなたの状況ではすべきあなたはjavadocコメントを追加すること」だと思います。アプリのスコープやコンテキストがわからない場合、どのようにして適切なものを知ることができますか？
この公開コード（つまり、APIなど、他のユーザーがアクセスするためのコード）の場合は、すべてのパラメーターを文書化します。読者があなたと同じくらいプロジェクトについて知っていると思い込まないでください。しかし、それ以外の場合は、あなたとあなたのチームがあなた自身の決定を下す必要があります。