Código de auto-documentação vs Javadocs?

Recentemente, tenho trabalhado na refatoração de partes da base de código com a qual estou lidando atualmente - não apenas para entender melhor, mas também para facilitar para outras pessoas que estão trabalhando no código.

Costumo me apoiar no lado de pensar que o código de auto-documentação é bom . Eu apenas acho que é mais limpo e se o código fala por si, bem ... Isso é ótimo .

Por outro lado, temos documentação como javadocs. Também gosto disso, mas há um certo risco de que os comentários aqui sejam desatualizados (assim como os comentários em geral, é claro). No entanto, se estiverem atualizados, podem ser extremamente úteis, por exemplo, no entendimento de um algoritmo complexo.

Quais são as melhores práticas para isso? Onde você define a linha entre o código de auto-documentação e os javadocs?

O código de auto-documentação (e os comentários no código) e os Javadoc têm dois públicos-alvo muito diferentes.

O código e os comentários que permanecem no arquivo de código são para desenvolvedores. Você deseja abordar as preocupações deles aqui - facilite a compreensão do que o código faz e por que o código é do jeito que é. O uso de nomes de variáveis ​​apropriados, métodos, classes e assim por diante (código de auto-documentação), juntamente com os comentários, consegue isso.

Os comentários Javadoc geralmente são para usuários da API. Eles também são desenvolvedores, mas não se importam com a estrutura interna do sistema, apenas com as classes, métodos, entradas e saídas do sistema. O código está contido em uma caixa preta. Esses comentários devem ser usados ​​para explicar como executar determinadas tarefas, quais são os resultados esperados das operações, quando são lançadas exceções e o que significam os valores de entrada. Dado um conjunto de documentação gerado por Javadoc, eu devo entender completamente como usar suas interfaces sem nunca olhar para uma linha do seu código.

Código diz como . Os comentários dizem o porquê e talvez até por que não .

É seu trabalho fornecer aos futuros leitores e mantenedores do seu código. Coloque tudo o que puder no código e o restante nos comentários.

Observe que as coisas mais difíceis de capturar são as decisões de design - lembre-se delas também.

O uso de Javadocs não faz uma diferença real - como os documentos gerados contêm o nome de suas funções juntamente com o texto dos comentários, não há absolutamente nenhuma razão para que você repita algo nos comentários que esteja claro no próprio nome da função.

Se, por outro lado, você tem uma função na qual é necessário examinar a implementação primeiro para entender para que serve (não disponibilizando essas informações para os Javadocs), o código é IMHO, não se autodocumenta, não importa quão clara é a implementação.

Eu acho que com javadocs, as coisas são as mesmas de qualquer documentação - a regra principal é:

siga a audiência

Não muitas pessoas lêem seus javadocs? Se sim, faz sentido investir esforços para acertar.

Seus leitores tendem a pular a leitura do código em favor do estudo de javadocs? Se sim, faz duas vezes mais sentido gastar esforços em escrevê-lo bem.

• Este é exatamente o caso da documentação do JDK . Acho que a Sun / Oracle gastou muito esforço nisso e eles parecem ter um bom retorno nos documentos da API que são muito usados ​​pela comunidade.

Agora, é o seu caso? Caso contrário, pense duas vezes se os esforços investidos em javadocs são justificados.

Como já apontado acima, ouça o público para descobrir o caminho.

• Se você ouvir reclamações ativas sobre documentação insuficiente, considere investir para aprimorá-la.
   
  Se, por outro lado, tudo o que você ouve são desenvolvedores reclamando sobre regras irrelevantes, forçando-os a perder tempo com a digitação inútil, então são grandes as chances de que seus esforços no javadocs sejam como investir em hipotecas subprime . Pense em melhores investimentos.

Eu só quero comentar sobre a preocupação de que os comentários do Javadoc possam estar desatualizados. Enquanto @JonathanMerlet está certo ao dizer que o Javadoc deve ser estável, você também pode ajudar revisando o Javadoc e os comentários e o código durante a revisão por pares. Os comentários correspondem ao que o código está fazendo? Caso contrário, o que está incorreto e insista para que o desenvolvedor o corrija. Tente incentivar outros desenvolvedores a fazer o mesmo. Isso ajuda a manter não apenas a documentação externa (comentários do Javadoc) atualizada, mas também quaisquer comentários regulares sobre o código. Isso ajuda os desenvolvedores que vierem depois da refatoração a entender o código de maneira mais rápida e fácil e facilita a manutenção no código no futuro.

Eu acho que o javadocs é apropriado para as partes que devem permanecer estáveis ​​(API), para minimizar o risco de comentários desatualizados, enquanto o código de auto-documentação é ótimo para o que está sujeito a alterações frequentes (implementação). Obviamente, as APIs podem mudar durante o curso do projeto, mas ter o cabeçalho imediatamente antes da declaração, mantendo as duas coisas sincronizadas não é tão difícil (comparado a comentários em várias linhas que explicam várias linhas de código)