Solucionado (ver solução)
Solucionado
(ver solução)
2
respostas

[Dúvida] Boas práticas com Javadoc

Olá gente, tudo bem?

Pensando em termos de código limpo, é uma boa prática criar um Javadoc para cada classe e método que eu criar (Sei que no dia a dia do desenvolvedor não é tão simples assim arrumar tempo para documentar tudo)?

Minha pergunta se deve ao fato de que sei que é de bom tom não se exceder na quantidade de comentários no código e que basicamente o Javadoc é um comentário.

Valeu!

2 respostas
solução!

Opa Luís! Tudo tranquilo e você?

Neste caso o javadoc e comentários são coisas distintas e possuem propositos diferentes.

  • Os comentários são utilizados para auxiliar o entendimento a nível de código. Que possui o intuito de prover informações ou explanações sobre as variáveis, métodos, classes ou alguma declaração. Como você citou o clean code, temos que utlizar sempre as boas práticas para evitar comentários no código.
  • O javadoc já são voltados para usuários da API (nos desenvolvedores), por exemplo alguma biblioteca. Esses comentários do javadoc devem ser usados para explicar como executar determinadas tarefas, quais são os resultados esperados, quando as exceções são lançadas e o que significam os valores de entrada. Dado um conjunto de documentação gerado por Javadoc, devo entender completamente como usar suas interfaces sem nunca olhar para uma linha de seu código.

Relacionado a documentação vou indicar algumas que são bastante usadas e que você pode explorar um pouco:

Swagger: API Documentation & Design Tools for Teams

Spring REST Docs

Valeu Vinícius! Ajudou demais!