Escrevendo comentários de documentos java para casos de teste de unidade

Na minha opinião, os casos de teste de unidade em si servem como uma documentação para o código. Minha empresa quer que eu escreva comentários detalhados sobre java doc sobre os casos de teste de unidade. É necessário fazer isso? Você escreve comentários assim?

unit-testing documentation

— Vinoth Kumar CM
fonte

presumindo que o código de teste seja bem escrito e legível, o valor principal de um comentário desse tipo no código de teste é uma declaração de intenções. Isso pode ser muito valioso para os revisores de código, mesmo para você mesmo daqui a alguns anos, pois permite que você julgar o código que foi escrito é fazer o que é suposto fazer ou testar o que é suposto testar. Secundariamente, você pode usar sistemas como JAVADOC ou até mesmo um script simples para extrair os nomes e comentários dos testes do código, para criar uma documentação rápida sobre quais testes você tem e o que eles estão fazendo.

— Chuck van der Linden

Respostas:

O que faço é comentar JAVADOC:

a classe, indicando qual classe é testada em unidade (embora deva ser óbvio, pois a melhor prática nesse assunto sugere que o nome do caso de teste deve ser o nome da classe + "Teste" ou + "TestCase"). Isso é feito usando o comentário JAVADOC do {@link XXXClass}
os métodos, indicando qual método foi testado ({@link XXXClass # method1}). Às vezes, preciso ter vários métodos de teste para um método de uma classe para testar adequadamente todos os caminhos. Quando isso acontece, escrevo uma linha adicional informando qual caminho estou testando (mas nunca me afasto da minha convenção de uma linha)

Além disso, nenhum outro comentário. Para chamar a atenção deles para outro lugar, talvez você possa usar algo como Cobertura para gerar belos gráficos de cobertura de código e fazê-los felizes assim :-)

Nota adicional: Estou me referindo a casos de teste de unidade, se estamos falando de casos de teste de integração, então uma ou duas linhas para explicar o que está acontecendo pode ser realmente necessário ...

— Jalayn
fonte

Os requisitos de documentação para qualquer código são abordados de maneira bastante completa nas respostas a esta pergunta: Meu chefe deseja uma explicação em inglês narrada linha por linha do nosso código

Como um resumo das respostas, você verá lá: "Depende da sua situação". Há casos em que isso é razoável (e incentivado) e outros em que é uma perda de tempo.

— blueberryfields
fonte

Os comentários do Javadoc podem ser extraídos e formatados em um documento de referência separado, os testes de unidade não. Além disso, lembre-se de que o que você escreve em palavras pode ser diferente do código real e, geralmente, você está descrevendo em palavras o comportamento real esperado. Uma das maneiras de encontrar bugs é comparar a documentação com o código real, se eles não corresponderem - é um bug (em um deles e, às vezes, em ambos).

O teste de unidade é para teste, não para documentação. Usar o teste de unidade como documentação está errado e não deve ser feito.

— littleadv
fonte

Acho que um bom conjunto de testes de unidade é imensamente útil na documentação de códigos. Eles fornecem uma implementação de referência sobre como o código de alguém deve ser usado, juntamente com a prova de que o código se comporta corretamente quando usado dessa maneira.

— Bill Michell

@ Bill - nenhum argumento sobre isso, é útil. Não substitui a documentação adequada.

— Littleadv 21/09/11

Depende do público para sua documentação - mas em alguns casos você está definitivamente correto.

— Bill Michell

O ideal é que os testes de unidade não sejam a única documentação de um sistema - mas, no mundo real, 9 em cada 10 projetos estão trabalhando com código legado, onde pode ser considerado uma sorte ter qualquer documentação. Nesse caso, prefiro um bom conjunto de testes de unidade em execução e aprovação em vez de vários documentos que podem estar totalmente fora de sincronia com o código real. (Sim, mesmo a lata Javadoc.)

— Péter Török

@ PéterTörök Sim ... Eu me mudei entre vários empregadores diferentes, algumas empresas muito conhecidas. Muito código legado. Os únicos testes de unidade de todos os tempos - os que escrevi. Então você teve muita sorte. Não presuma que o que você viu é o que acontece em todos os lugares. E mesmo se você tiver um conjunto de testes de unidade ... Quem disse que eles estão corretos? Quem disse que eles cobrem o que deveriam? Quem disse que os resultados esperados são o que são? Por que você supõe que os testes de unidade não estão fora de sincronia? Só porque eles "passam"? Absurdo.

— Littleadv