Como outros já disseram, há uma diferença entre comentários documentando API e comentários em linha. Do meu ponto de vista, a principal diferença é que um comentário em linha é lido ao lado do código , enquanto um comentário da documentação é lido ao lado da assinatura do que você está comentando.
Por isso, podemos aplicar o mesmo princípio DRY . O comentário está dizendo a mesma coisa que a assinatura? Vamos ver o seu exemplo:
Retrieves a product by its id
Esta parte apenas repete o que já vemos no nome GetById
mais o tipo de retorno Product
. Também levanta a questão de qual é a diferença entre "obter" e "recuperar", e o que o código versus comentário tem sobre essa distinção. Então é desnecessário e um pouco confuso. Se alguma coisa, está ficando no caminho da segunda parte realmente útil do comentário:
returns null if no product was found.
Ah! Isso é algo que definitivamente não podemos ter certeza apenas da assinatura e fornece informações úteis.
Agora, leve isso um passo adiante. Quando as pessoas falam sobre comentários como cheiros de código, a questão não é se o código como é precisa de um comentário, mas se o comentário indica que o código poderia ser escrito melhor, para expressar as informações no Comente. Isso é o que significa "cheiro de código" - não significa "não faça isso!", Significa "se você está fazendo isso, pode ser um sinal de que há um problema".
Então, se seus colegas lhe disserem que esse comentário sobre null é um cheiro de código, você deve simplesmente perguntar a eles: "Ok, como devo expressar isso então?" Se eles tiverem uma resposta viável, você aprendeu alguma coisa. Se não, provavelmente vai matar suas queixas mortas.
Em relação a este caso específico, geralmente a questão nula é bem conhecida por ser difícil. Há uma base de código de razão que está repleta de cláusulas de guarda, por que as verificações de nulos são uma pré-condição popular para contratos de código, por que a existência de nulo foi chamada de "erro de bilhões de dólares". Não há muitas opções viáveis. Um popular, no entanto, encontrado em C # é a convenção Try...
:
public bool TryGetById(int productId, out Product product);
Em outros idiomas, pode ser idiomático usar um tipo (geralmente chamado de Optional
ou Maybe
) para indicar um resultado que pode ou não estar lá:
public Optional<Product> GetById(int productId);
Então, de certa forma, essa postura antiesclarismo nos levou a algum lugar: pelo menos pensamos se esse comentário representa um cheiro e quais alternativas podem existir para nós.
Se devemos na verdade preferir estes ao longo da assinatura original é um outro debate, mas pelo menos temos opções para expressar através de código em vez de comentários o que acontece quando nenhum produto é encontrado. Você deve discutir com seus colegas qual dessas opções eles acham que é melhor e por quê, e esperamos que ajude a seguir além das afirmações dogmáticas sobre os comentários.