Os testes devem ser JUnit javadocced?

Question

Eu tenho um número de casos de teste JUnit que actualmente não estão documentados com comentários Javadoc.

O resto do meu código está documentado, mas eu estou querendo saber se é mesmo a pena o esforço para documentar esses testes.

Answer 1

Se o objetivo do teste é óbvio, eu não me incomodo documentá-lo.

Se é não-óbvia porque lida com uma situação obscura - ou se eu quiser para se referir a um erro específico, por exemplo - em que caso eu vou adicionar documentação. Eu não documentar exceções jogar etc embora - apenas um rápido resumo do método. Isso acontece relativamente rara. Eu sou mais provável para adicionar documentação para métodos auxiliares usados ??dentro de vários testes.

Answer 2

Eu não encontrar qualquer valor em javadocing os casos de teste. Acabei de fazer o suficiente nome do método descritivo saber o propósito do teste.

Em Ruby, eu sei que existem ferramentas para criar um documento a partir do nome dos testes, mas eu não vi um desses em Java.

Answer 3

Se javadoc ou não, eu acho que testes de unidade deve definitivamente ser documentado. Nos casos em que não existe especificação formal, os testes de unidade são o que mais se aproxima de definir o comportamento esperado do código. Ao documentar os casos de teste, você vai torná-lo muito claro para o leitor o que o teste está testando, e por isso é testá-lo.

Answer 4

Ao pensar sobre os testes como uma documentação, não faz muito sentido para "documentar a documentação". O nome de cada teste já em si deve descrever de que o que é o propósito dos testes -. O que é o comportamento que está sendo especificado por esse teste

Use longa, nomes descritivos para os testes, e manter o código de teste mais legível possível.

Por exemplo ter um olhar para os casos de teste neste projecto . Será que algum deles fazer algo que não é por demais evidente, olhando para o nome dos testes e o código de teste?

É apenas em alguns casos raros, quando o código de teste é obscura, que os comentários são necessários testes. Por exemplo, se você está testando código de multi-threaded e o código de teste faz coisas estranhas, a fim de se certificar de que o código é executado teste na ordem correta. Mas, mesmo nesses casos, um comentário é uma desculpas para não escrever o código de teste limpo.

Answer 5

Eu não vejo por que você deve tratar casos de teste de forma diferente do que o seu código de produção no que diz respeito aos comentários.

Answer 6

Eu acho que é valioso para javadoc as condições em que os testes passam.

Answer 7

É heresia sugerir que os comentários de código são um anti-padrão? Concordo com as respostas acima, idealmente seu código seria suficiente descritivo contar com sem comentários. Isto é especialmente verdadeiro se você estiver em um ambiente (empresa), onde as pessoas tendem a atualizar o código sem atualizar comentários até comentários se tornam enganosa.

Answer 8

sim inferno. mesmo que seja apenas ...

criar ordem, a fim editar, salvar, carregar e verificá-lo.

Se seu um teste muito simples, então talvez não.

Eu acho que, como alterações de código, por vezes, a razão para o teste não é uma óbvia como era antes.

Answer 9

Talvez você poderia conseguir alguém que não está totalmente familiarizado com o seu código para dar-lhe algum feedback rápido sobre se os testes são facilmente entendidas como elas são.

No trabalho da empresa I, nós tentamos dar aos nossos testes nomes descritivos e da complexidade do documento, mas é muitas vezes difícil de obter este "direito" com o primeiro rascunho porque as coisas que são óbvias para o desenvolvedor nem sempre são óbvias para outros.

Os testes são tratados como código e são apresentadas como parte de um processo de revisão por pares para que a nossa (pequena), a equipe pode comentar sobre se um teste é facilmente compreendido ou não.

Se um teste é um pouco confuso, podemos atualizar o nome ou a documentação em conformidade e que sair com uma medida melhor do que funciona eo que não funciona.