É necessário escrever um comentário javadoc para TODOS os parâmetros na assinatura de um método?

Um dos desenvolvedores da minha equipe acredita que é necessário escrever um comentário javadoc para TODOS os parâmetros na assinatura de um método. Não acho que isso seja necessário e, de fato, acho que pode até ser prejudicial.

Primeiro, acho que os nomes dos parâmetros devem ser descritivos e auto-documentados. Se não for imediatamente óbvio para que servem os seus parâmetros, você provavelmente está fazendo errado. No entanto, entendo que, às vezes, não está claro para que serve um parâmetro, portanto, nesses casos, sim, você deve escrever um comentário em javadoc explicando o parâmetro.

Mas acho que é desnecessário fazer isso para CADA parâmetro. Se já é óbvio para que serve o parâmetro, o comentário do javadoc é redundante; você está apenas criando trabalho extra para si mesmo. Além disso, você está criando trabalho extra para quem precisa manter seu código. Os métodos mudam com o tempo e a manutenção de comentários é quase tão importante quanto a manutenção do seu código. Quantas vezes você já viu um comentário como "X faz Y por razão de Z" apenas para ver que o comentário está desatualizado e, de fato, o método nem aceita mais o parâmetro X? Isso acontece o tempo todo, porque as pessoas esquecem de atualizar os comentários. Eu argumentaria que um comentário enganoso é mais prejudicial do que nenhum comentário. E, portanto, há o risco de comentar demais: criando documentação desnecessária, você '

No entanto, respeito o outro desenvolvedor da minha equipe e aceito que talvez ele esteja certo e eu esteja errado. É por isso que trago minha pergunta a vocês, colegas desenvolvedores: é realmente necessário escrever um comentário javadoc para TODOS os parâmetros? Suponha aqui que o código seja interno da minha empresa e não seja consumido por terceiros.

As anotações Javadoc (e, na palavra Microsoft, XMLDoc) não são comentários , são documentação .

Os comentários podem ser tão esparsos quanto você deseja; supondo que seu código seja legível pela metade, comentários comuns são meramente indicativos para ajudar futuros desenvolvedores a entender / manter o código que eles já estão observando há duas horas.

A documentação representa um contrato entre uma unidade de código e seus chamadores. Faz parte da API pública. Sempre assuma que o Javadoc / XMLdoc acabará em um arquivo de ajuda ou em um pop-up de preenchimento automático / intellisense / de conclusão de código e seja observado por pessoas que não estão examinando as partes internas do seu código, mas desejam apenas usá- lo para algum propósito de próprios.

Os nomes de argumentos / parâmetros nunca são auto-explicativos. Você sempre pensa que são quando passou o último dia trabalhando no código, mas tente voltar depois de duas semanas de férias e verá como eles realmente são inúteis.

Não me entenda mal - é importante escolher nomes significativos para variáveis ​​e argumentos. Mas isso é um problema de código, não de documentação. Não tome a frase "auto-documentação" muito literalmente; isso se refere ao contexto da documentação interna (comentários), não da documentação externa (contratos).

Comente tudo ou comente nada (obviamente comentar tudo é uma escolha muito melhor). Pense em alguém usando seu código, revisando sua API diretamente no seu arquivo de origem ou em um arquivo de documento gerado (por exemplo, saída doxygen). Inconsistências geralmente levam a confusão, o que leva ao tempo gasto na busca pela origem para descobrir por que algo não foi comentado, o que leva ao desperdício de tempo que poderia ter sido evitado se o parâmetro tivesse sido comentado em primeiro lugar.

Lembre-se: algo que faça sentido para você pode ser interpretado de maneira completamente diferente por outra pessoa, não importa o quão mundano você pense que é (pense em alguém que não é tão forte em inglês lendo e tentando entender seu código).

Dito tudo isso, se o outro desenvolvedor está enfatizando a importância de documentar tudo, é necessário colocar tanta ênfase (se não mais) em manter a documentação atualizada. Como você afirmou, não há muito pior do que ter comentários desatualizados (tão ruins quanto os documentos omitidos).

Vamos começar com a suposição de que os ciclos do desenvolvedor são o recurso que estamos tentando conservar.

Isso significa que os desenvolvedores não devem perder tempo documentando parâmetros evidentes e retornando valores, certo?

Bem, vamos detalhar.

Se documentarmos tudo, supondo que os comentários marginais sejam realmente triviais e não exijam reflexão ou pesquisa, o custo será o tempo adicional para digitar o comentário e corrigir erros de digitação.

Se escolhermos, os custos são:

• Ter e vencer a discussão com os outros desenvolvedores da sua equipe que acham que tudo deve ser documentado.
• Para cada parâmetro, determinando se isso deve ou não ser documentado.
• Mais argumentos com sua equipe quando alguém tem uma opinião diferente sobre se um parâmetro deveria ter sido documentado.
• O tempo gasto pesquisando o código e pesquisando quando um parâmetro considerado auto-explicativo acaba não sendo assim.

Então, eu estaria inclinado a documentar tudo. A desvantagem é definitiva, mas está contida.

Se você estiver escrevendo o Javadoc de qualquer maneira, é melhor escrevê-lo completamente, mesmo incluindo os parâmetros "óbvios". Eles podem ser óbvios para você ou para o outro desenvolvedor, mas qualquer pessoa nova que esteja visualizando isso se beneficiaria de conhecer a intenção de cada parâmetro.

Quanto à manutenção do Javadoc corretamente, você precisa usar ferramentas para o seu desenvolvimento que o ajudem com isso. Eclipse vem à mente. Obviamente, se for importante, você deve garantir que todos da equipe façam sua parte para manter o código, incluindo comentários.

Não esqueça que o javadoc pode ser visível enquanto separado do código, o principal exemplo é a própria API Java . Ao não incluir o javadoc para cada parâmetro em um método, você está deturpando o método e como ele pode ser usado.

'necessário' é completamente subjetivo. Acho que o que você está perguntando é: "na sua situação, você deve adicionar um comentário javadoc". Sem conhecer o escopo ou o contexto do seu aplicativo, como devemos saber o que é apropriado para você?

Se esse código público (ou seja, código destinado a outros acessarem, como uma API), sim, documente todos os parâmetros. Não assuma que o leitor conhece o projeto tanto quanto você. Caso contrário, cabe a você e sua equipe tomar suas próprias decisões.