メソッドの署名のすべてのパラメーターにjavadocコメントを書く必要がありますか？

私のチームの開発者の1人は、メソッドの署名のEVERYパラメーターにjavadocコメントを書く必要があると考えています。私はこれが必要だとは思わないし、実際、それは有害でさえあると思う。

まず、パラメーター名は説明的で自己文書化されるべきだと思います。パラメータの目的がすぐに分からない場合は、おそらく間違っています。ただし、パラメータの目的が不明な場合があることは理解しています。そのため、その場合は、パラメータを説明するjavadocコメントを作成する必要があります。

しかし、すべてのパラメーターに対してこれを行う必要はないと思います。パラメータの目的がすでに明らかな場合、javadocコメントは冗長です。あなた自身のために余分な仕事を作成しているだけです。さらに、コードを保守する必要がある人のために余分な作業を作成しています。メソッドは時間とともに変化し、コメントを維持することはコードを維持することとほぼ同じくらい重要です。「XはYをZの理由で行う」などのコメントを何回見て、そのコメントが古いことを確認しましたが、実際にはメソッドはXパラメーターさえも取りません。人々はコメントを更新するのを忘れているので、それは常に起こります。誤解を招くコメントは、まったくコメントしないよりも有害であると主張します。したがって、過剰なコメントの危険性があります。不要なドキュメントを作成することにより、

しかし、私は自分のチームの他の開発者を尊重し、おそらく彼が正しいと私は間違っていることを受け入れます。だからこそ、仲間の開発者に質問を投げかけます。実際、すべてのパラメーターにjavadocコメントを書く必要がありますか？ここでは、コードは会社の内部にあり、外部の第三者によって消費されることはないと想定しています。

Javadoc（Microsoftの言葉ではXMLDoc）アノテーションはコメントではなく、ドキュメントです。

コメントは、必要に応じてスパースにすることができます。コードが途中まで読めると仮定すると、通常のコメントは、将来の開発者が既に2時間見つめているコードを理解/維持するための単なる道しるべです。

ドキュメントが表す契約コードのユニットと発信者との間です。これは、パブリックAPIの一部です。常にそののJavadoc / XMLDOCは、ヘルプファイルやオートコンプリート/インテリセンス/コード補完ポップアップのいずれかで終わるだろう、としている人々によって観察することが前提としないで、あなたのコードの内部を調べ単にたい使用のいくつかの目的のためにそれを彼ら自身。

引数/パラメータ名は決して一目瞭然ではありません。過去1日をコードの作業に費やしたのは彼らだといつも思っていますが、2週間の休暇の後に戻ってみると、本当に役に立たないことがわかります。

私を誤解しないでください-変数と引数に意味のある名前を選択することが重要です。しかし、それはコードの問題であり、ドキュメントの問題ではありません。「自己文書化」というフレーズを文字通りに受け取らないでください。これは、外部ドキュメント（契約）ではなく、内部ドキュメント（コメント）のコンテキストでの意味です。

すべてコメントするか、何もコメントしないでください（明らかにすべてコメントする方がはるかに良い選択です）。ソースファイルまたは生成されたdocファイル（つまり、doxygen出力）でAPIを直接レビューするコードを使用している人について考えてください。通常、矛盾は混乱を招き、ソースを掘り下げて何がコメントされなかったのかを理解するのに時間を費やします。

覚えておいてください：あなたにとって理にかなっていることは、あなたがどんなに平凡だと思っても、他の誰かによって完全に異なって解釈されるかもしれません（あなたのコードを読んで理解しようとするほど英語に強くない人について考えてください）。

そうは言っても、他の開発者がすべてを文書化することの重要性を強調している場合は、文書を最新の状態に保つことに（それ以上ではないにしても）同じくらい重点を置く必要があります。あなたが述べたように、時代遅れのコメントを持っているよりもそれほど悪いことはありません（ドキュメントを省略するよりも悪くないにしても、同じくらい悪いです）。

開発者サイクルが節約しようとしているリソースであるという仮定から始めましょう。

つまり、開発者は自明のパラメーターと戻り値の文書化に時間を浪費すべきではないということです。

さて、それを分解しましょう。

限界コメントが本当に些細であり、思考や研究を必要としないと仮定して、すべてを文書化する場合、コストはコメントを実際に入力してタイプミスを修正するための追加時間です。

選択して選択した場合のコストは次のとおりです。

• すべてを文書化する必要があると考えるチームの他の開発者との議論を持ち、勝ちます。
• 各パラメーターについて、これを文書化する必要があるかどうかを決定します。
• パラメータが文書化されるべきかどうかについて誰かが異なる意見を持っている場合、チームとのより多くの議論。
• 自明であると見なされたパラメーターがそうではないことが判明した場合、コードの探索と調査に時間を費やします。

だから、私はすべてを文書化したいと思うでしょう。欠点は明確ですが、含まれています。

とにかくJavadocを作成している場合は、「明白な」パラメーターを含めて完全に作成することもできます。それらはあなたや他の開発者には明らかかもしれませんが、それを見ている新しい人はそれぞれのパラメータの意図を知ることから恩恵を受けるでしょう。

Javadocを適切に維持するには、開発に役立つツールを使用する必要があります。Eclipseが思い浮かびます。もちろん、それが重要な場合は、チームの全員がコメントを含めてコードを維持するために自分の役割を果たさなければなりません。

Javadocをコードから切り離して表示できることを忘れないでください。主な例はJava API自体です。メソッドのすべてのパラメーターにjavadocを含めないことにより、メソッドとその使用方法を誤って伝えます。

「必要」は完全に主観的です。あなたが尋ねているのは、「あなたの状況では、javadocコメントを追加する必要があります」と思います。アプリの範囲やコンテキストがわからない場合、どのようなものが適切かを知るにはどうすればよいですか？

この公開用のコード（つまり、APIなど、他の人がアクセスすることを意図したコード）であれば、すべてのパラメーターを文書化します。読者があなたと同じくらいプロジェクトについて知っていると思い込まないでください。しかし、それ以外の場合は、あなたとあなたのチームがあなた自身の決定を下す必要があります。