web-dev-qa-db-ja.com

JUnitテストクラスのJavadoc？

JdocテストのクラスとメソッドにJavadocコメントを配置することはベストプラクティスですか？それとも、それらは読みやすく、テストの意図を説明する必要がないほど単純である必要があるという考えですか？

junitjavadoc
33
HDave

画面上が乱雑になるので、私は個人的にjavadocコメントを控えめに使用しています。より自己記述的な方法でクラス、関数、または変数に名前を付けることができる場合は、コメントを優先します。このトピックについて読むのに最適な本は、ロバート・C・マーティン（別名アンクル・ボブ）による クリーンコード です。

私の個人的な好みは、クラスとメソッドの両方を説明的にすることです。

class ANewEventManager {
   @Test
   public void shouldAllowClassesToSubscribeToEvents() {
        /* Test logic here */
   }
}

このアプローチの1つの利点は、コードを参照する前に、junitの出力で何が失敗しているかを簡単に確認できることです。

21
Martin

私はテストでJavadocをよく使用しています。ただし、Javadocに独自のタグを追加した場合にのみ、非常に役立ちます。

ここでの主な目的はプロジェクトに貢献している他の開発者がテストを理解できるようにすることです。そのため、実際のjavadocを生成する必要すらありません。

/**
 * Create a valid account.
 * @result Account will be persisted without any errors,
 *         and Account.getId() will no longer be <code>null</code>
 */
@Test
public void createValidAccount() {
    accountService.create(account);
    assertNotNull(account.getId());
}

次に、新しいタグが追加されたことをmavenのJavadocプラグインに通知する必要があります。

<build>
    <plugins>
        <plugin>
            <groupId>org.Apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.8</version>
            <configuration>
                <tags>
                    <tag>
                        <name>result</name>
                        <placement>a</placement>
                        <head>Test assertion :</head>
                    </tag>
                </tags>
            </configuration>             
        </plugin>    
    </plugins>        
</build>

あとは、mavenプラグインを呼び出すだけです。

javadoc:test-javadoc (or javadoc:test-aggregate for multi-module projects)

これはかなり簡単な例ですが、より複雑なテストを実行する場合、自己記述的なメソッド名を使用してテストを説明することは不可能です。

37
Foumpie

UTのコメントも好きです。ユースケースを数秒で理解するのに役立ちます。

私は小さなライブラリを作成して、あらゆる種類のレポートのスタックトレースに説明を含めました。レポートをチェックしている人なら誰でも簡単に問題に入ることができます。

ライブラリ名はFrutillaです。自由に使用してください https://github.com/ignaciotcrespo/frutilla

0
Ignacio Tomas Crespo