JUnitテストはjavadoccedする必要がありますか？

Question

現在、Javadocコメントで文書化されていないJUnitテストケースがいくつかあります。

残りのコードは文書化されていますが、これらのテストを文書化するだけの価値があるかどうか疑問に思っています。

Answer 1

テストの目的が明らかな場合は、わざわざ文書化しません。

いくつかのあいまいな状況を扱っているために非自明な場合、または特定のバグを参照したい場合など、そのケースではドキュメントを追加します。ただし、例外のスローなどは文書化しません-メソッドの簡単な要約です。これは比較的まれにしか起こりません。複数のテストで使用されるヘルパーメソッドのドキュメントを追加する可能性が高くなります。

Answer 2

テストケースのjavadocingに値が見つかりません。メソッドの名前を、テストの目的を知るのに十分な説明的なものにするだけです。

Rubyには、テストの名前からドキュメントを作成するツールがあることは知っていますが、Javaでこれらの1つを見たことはありません。

Answer 3

javadocであろうとなかろうと、ユニットテストは必ず文書化されるべきだと思います。正式な仕様が存在しない場合、単体テストは、コードの予想される動作を定義するのに最も近いものです。テストケースを文書化することにより、テストが何をテストしているのか、なぜテストしているのかを読者に非常に明確にします。

Answer 4

テストをドキュメントとして考える場合、「ドキュメントをドキュメント化する」ことはあまり意味がありません。各テストの名前は、それ自体でテストの目的、つまりそのテストで指定されている動作とは何かをすでに説明しているはずです。

テストにはわかりやすい長い名前を使用し、テストコードはできるだけ読みやすくします。

たとえば、テストケースをご覧くださいこのプロジェクト内。それらのいずれかが、テストの名前とテストコードを見ることによって露骨に明らかではない何かをしますか？

まれに、テストコードが不明瞭な場合にのみ、テストでコメントが必要になります。たとえば、マルチスレッドコードをテストしているときに、テストコードが正しい順序で実行されることを確認するために、テストコードが奇妙な動作をする場合。ただし、そのような場合でも、コメントは、よりクリーンなテストコードを記述しないことに対する謝罪です。 p>

Answer 5

コメントに関して、実稼働コードとは異なる方法でテストケースを処理する必要がある理由はわかりません。

Answer 6

テストに合格する条件をjavadocすることは有益だと思います。

Answer 7

コードコメントがアンチパターンであることを示唆するのは異端ですか？上記の答えに同意します。理想的には、あなたのコードはコメントなしで信頼できるほど記述的であることが理想です。これは、ユーザーがコメントを更新せずにコードを更新する傾向がある（エンタープライズ）環境にいる場合に特に当てはまり、コメントが誤解を招くようになります。

Answer 8

はい。ただ...

注文の作成、注文の編集、保存、読み込み＆amp;確認してください。

本当に簡単なテストであれば、そうでないかもしれません。

コードが変更されると、テストの理由が以前ほど明白ではないことがあります。

Answer 9

コードに完全に精通していない人を探して、テストがそのまま理解されているかどうかについて迅速なフィードバックを得ることができます。

私が働いている会社では、テストにわかりやすい名前とドキュメントの複雑さを与えようとしていますが、これを「正しい」ものにするのは難しい場合がよくあります。開発者にとって明らかなことは、他の人にとって常に明白であるとは限らないためです。

テストはコードのように扱われ、ピアレビュープロセスの一部として送信されるため、（小さな）チームはテストが簡単に理解できるかどうかについてコメントできます。

テストが少しわかりにくい場合は、それに応じて名前またはドキュメントを更新することができ、機能するものと機能しないもののより良いゲージが得られます。