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

17

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.

sangfroid
fonte
Muitos Java IDEs (Intellij em particular) irá marcar um parâmetro Javadoc faltando como um aviso documentação
Gary Rowe
O NetBeans e o Eclipse também.
Davor raldralo

Respostas:

38

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).

Aaronaught
fonte
1
+1: é tão essencial quanto o próprio código. Apenas não possui bons testes automatizados.
S.Lott
Se os parâmetros para um método incluem, por exemplo, três pares de coordenadas X e Y que serão interpretados como cantos adjacentes de um paralelogramo, é mais útil ter seis pequenos pedaços de documentação, um para cada parâmetro, ou para descrever a finalidade do método em termos de paralelogramo (x1, y1), (x2, y2), (x3, y3) e (x1 + x3-x2, y1 + y3-y2) [o último sendo o oposto (x2, y2)]? Se o objetivo do método for definido em termos de nomes de parâmetros, acho que documentação adicional sobre os parâmetros seria, em muitos casos, supérflua.
Supercat
1
@ supercat: Eu diria que, nesse caso, você deve refatorar, para ter um único tipo de dados Point, e a função simplesmente leva três Points(ou melhor ainda, um array / iterável deles). Quanto mais parâmetros um método tem, mais difícil de chamar e mais instável sua especificação tende a se tornar ao longo do tempo.
Aaronaught 07/02
@Aaronaught: Isso depende muito de como o método será usado. Ter uma sobrecarga que recebe três Pointe uma que recebe a Parallelogrampode ser útil se muitos chamadores puderem passar essas coisas. Se, no entanto, muitas Pointinstâncias acabassem sendo construídas sem nenhum objetivo, mas fossem passadas ao método uma vez , a construção dos objetos tornaria o código mais lento e mais difícil de ler. Se um idioma suportado agregados que seriam e se comportam como um bando de valores colados com fita adesiva, e pode-se passar um parâmetro de tipo de agregado apenas por ...
supercat
... colocando os valores entre chaves, isso pode ser bom do ponto de vista de desempenho e legibilidade. Java não tem esse conceito; um idioma baseado em JVM poderia suportar tal coisa eficientemente para parâmetros (um parâmetro Point p1pode ser traduzido int p1_x, int p1_y), mas a JVM não possui mecanismo eficiente para uma função retornar tal coisa.
supercat
12

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).

Demian Brecht
fonte
10

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.

JohnMcG
fonte
9

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.

Bernard
fonte
3

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.

Covar
fonte
"A - o argumento cujo valor absoluto deve ser determinado" realmente adiciona algo à documentação do Math.abs?
Kevin cline
@ Kevin Cline poderia ser útil para o disco de pensar ;-)
Gary Rowe
1

'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.

GrandmasterB
fonte
6
Eu acho que mesmo se não é público enfrenta, ajuda -me a compreender o meu próprio código quando eu olhar para trás anos depois: P
Demian Brecht
1
Essa abordagem também é conhecida como "Heck, faremos com que o novo cara tenha que ler o maldito código em quatro anos depois de partirmos". abordagem.
Tim Williscroft