Como lidar com a tautologia nos comentários? [fechadas]

Às vezes me encontro em situações em que a parte do código que estou escrevendo é (ou parece ser ) tão evidente que seu nome seria basicamente repetido como um comentário:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(Exemplo de C #, mas consulte a pergunta como independente de idioma).

Um comentário como esse é inútil; O que estou fazendo errado? É a escolha do nome que está errado? Como eu poderia comentar partes como essa melhor? Devo apenas pular o comentário para coisas assim?

Na maioria dos projetos em que trabalho, não há muito tempo para escrever comentários detalhados sobre cada aluno.

Isso não significa que não há tempo para comentários; pelo contrário, há tempo de sobra para comentários tautológicos que vomitam uma versão reformulada do que está sendo comentado. Eles funcionam muito bem como ponto de partida .

Especialmente considerando o uso de comentários do Visual Studio que acompanha o IntelliSense , é uma boa ideia começar com um pouco de informações sobre o campo:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

E, à medida que você continua codificando, quando não consegue se lembrar se UpdateLocationfoi o local para o qual a atualização ocorreu ou o local para o qual a atualização está sendo enviada, você deverá revisar o código. É nesse ponto que você deve adicionar essas informações adicionais:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Se outro programador perguntar sobre detalhes em um campo, atualize os comentários com essas informações:

Que tipo de atualização deve Example.UpdateLocationser usada para armazenar?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Assim como um programa tem bugs, bons comentários têm bugs que precisam ser resolvidos iterativamente. O objetivo dos comentários é ajudar a entender o código quando você o revisita seis meses depois e não consegue se lembrar de nada sobre como o programa funciona.

E, assim como a programação, seus comentários precisam começar em algum lugar. Os comentários tautológicos são os Hello World!comentários, à medida que você pratica a redação e atualização de documentação, sua documentação inicial se torna cada vez mais resistente.

Os comentários nunca devem duplicar seu código. Os comentários não devem responder à pergunta " como? ", Mas apenas " por quê? " E "o quê? ". Por que esse algoritmo é escolhido, quais são as suposições implícitas aqui (a menos que seu idioma seja poderoso o suficiente para expressá-lo com sistema de tipos, contratos e similares), qual é o motivo para fazer isso, etc.

Eu recomendo dar uma olhada na prática de programação alfabética para obter uma inspiração.

Os comentários devem descrever o código, não duplicá-lo. Este comentário do cabeçalho apenas duplica. Deixe isso de fora.

Deixe-os de fora!

Normalmente, é uma boa prática remover comentários onde as informações expressas neles já estão presentes em outros lugares. Se você pode expressar o objetivo de um método de forma clara e inequívoca, dando-lhe um bom nome, não há necessidade de comentar .

Coloque-os dentro!

Seu exemplo ilustra duas exceções a esta regra:

Primeiro, "UpdateLocation" pode (dependendo do contexto) ser ambíguo. Nesse caso, você precisa dar um nome melhor ou fornecer um comentário para remover a ambiguidade. Melhorar o nome geralmente é a melhor opção, mas isso nem sempre é possível (quando você está implementando uma API publicada, por exemplo).

Segundo, o "///" em C # indica um comentário que se destina a ser usado para gerar automaticamente a documentação. O IDE usa esses comentários para obter dicas de ferramentas, e existem ferramentas (Sandcastle) que podem gerar arquivos de ajuda e assim por diante a partir desses comentários. Como tal, existem argumentos para inserir esses comentários, mesmo que os métodos que eles documentam já tenham nomes descritivos. Mesmo assim, no entanto, muitos desenvolvedores experientes desaprovam a duplicação de informações. O fator decisivo deve ser as necessidades daqueles a quem a documentação se destina.

Discordo totalmente das respostas "não escreva comentários". Por quê? Deixe-me salientar, mudando um pouco o seu exemplo.

public Uri UpdateLocation ();

Então, o que essa função faz:

• Ele retorna o "local de atualização"? ou
• Ele "atualiza" o local e retorna o novo local?

Você pode ver que, sem um comentário, há ambiguidade. Um iniciante pode facilmente cometer o erro.

No seu exemplo, é uma propriedade, portanto os métodos "get / set" revelam que a segunda opção está incorreta e realmente significa "atualizar local" e não "atualizar o local". Mas é muito fácil cometer esse erro, especialmente em casos de palavras ambíguas, como "atualização". Jogue em segurança. Não confunda alguém novo com isso apenas para economizar alguns segundos do seu tempo.

/// <summary>blocos são usados ​​para gerar documentação para IntelliSense e documentação da API .

Portanto, se essa é uma API voltada para o público, você deve sempre incluir pelo menos um <summary>comentário, mesmo que o objetivo da função seja evidente para os leitores.

No entanto, essa é a exceção à regra; em geral, lembre-se de secar (não se repita) .

Preencha comentários como esse apenas se você souber como se beneficiaria de coisas assim; caso contrário, apenas limpe-os.

_{Para mim, o caso de benefício claro foi quando houve uma verificação automatizada para a falta de comentários e eu estava usando essa verificação para detectar código onde informações importantes precisavam ser preenchidas; por isso, estava preenchendo alguns espaços reservados - apenas para garantir que o relatório da ferramenta não contenha "alarmes falsos".}

Eu acho que sempre existe uma maneira de evitar duplicação flagrante . Ao longo dos anos, comecei a usar alguns "preenchimentos de modelo" para casos como o seu - principalmente como nome auto-descritivo e veja acima .

Para este exemplo em particular, eu usaria algo de "tipo auto-descritivo" (assumindo que não seja o caso em que a eliminação faria o trabalho), assim:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Um exemplo em que eu poderia usar os preenchimentos de tipo acima seria comentários Javadoc que exigem campos dedicados para retornar valor, parâmetros e exceções. Freqüentemente, acho que faz mais sentido descrever a maioria ou mesmo todos eles em uma única frase resumida, método que retorna <descreva o que é retornado> para parâmetros fornecidos <descreva parâmetros> . Em casos como esse, preencheu os campos formalmente obrigatórios com a simples vista acima , apontando o leitor para a descrição resumida.}

Aqui está uma pergunta que eu gostaria de me perguntar quando pensava em adicionar um comentário a uma seção do código: O que posso transmitir que ajudaria a próxima pessoa a entender melhor a intenção geral do código, para que eles possam atualizar, corrigir ou estendê-lo mais rápido e mais confiável?

Às vezes, a resposta correta para essa pergunta é que não há muito o que você pode adicionar nesse ponto do código, porque você já selecionou nomes e convenções que tornam a intenção o mais óbvia possível. Isso significa que você escreveu um código sólido de auto-documentação e que a inserção de um comentário provavelmente prejudicaria mais do que ajudaria. (Observe que comentários redundantes podem realmente prejudicar a confiabilidade do código ao longo do tempo, diminuindo a sincronização com o código real ao longo do tempo e dificultando a decifração da intenção real.

No entanto, em quase qualquer programa e em qualquer linguagem de programação, você encontrará pontos em que certos conceitos e decisões críticas tomadas pelo programador original - por você - não serão mais aparentes no código. Isso é inevitável porque um bom programador sempre programa para o futuro - ou seja, não apenas para fazer o programa funcionar uma vez, mas para fazer todas as suas muitas correções e versões futuras e extensões e modificações e portas e quem sabe o que fazer também funcionam corretamente. Esse último conjunto de metas é muito mais difícil e requer muito mais pensamento para se sair bem. Também é muito difícil expressar bem na maioria das linguagens de computador, que são mais focadas na funcionalidade - ou seja, em dizer o que isso faz. A versão do programa precisa ser executada no momento para torná-lo satisfatório.

Aqui está um exemplo simples do que quero dizer. Na maioria dos idiomas, uma pesquisa rápida em linha de uma pequena estrutura de dados terá complexidade suficiente para que alguém que a veja pela primeira vez provavelmente não reconheça imediatamente o que é. Essa é uma oportunidade para um bom comentário, porque você pode adicionar algo sobre a intenção do seu código que um leitor posterior provavelmente apreciará imediatamente como útil para decifrar os detalhes.

Por outro lado, em idiomas como o Prolog, baseado na lógica, expressar a pesquisa de uma pequena lista pode ser tão incrivelmente trivial e sucinta que qualquer comentário que você possa adicionar seria apenas ruído. Portanto, bons comentários são necessariamente dependentes do contexto. Isso inclui fatores como os pontos fortes do idioma que você está usando e o contexto geral do programa.

A linha inferior é esta: pense no futuro. Pergunte a si mesmo o que é importante e óbvio para você sobre como o programa deve ser entendido e modificado no futuro. [1]

Para aquelas partes do seu código que são realmente autodocumentadas, os comentários apenas adicionam ruído e aumentam o problema de coerência para versões futuras. Portanto, não os adicione lá.

Mas para as partes do seu código em que você tomou uma decisão crítica de várias opções, ou onde o código em si é complexo o suficiente para que sua finalidade seja obscura, adicione seu conhecimento especial na forma de um comentário. Um bom comentário nesse caso é aquele que permite que algum programador futuro saiba o que deve ser mantido o mesmo - esse é o conceito de uma afirmação invariável, aliás - e o que é bom mudar.

[1] Isso vai além da questão dos comentários, mas vale a pena mencionar: Se você acha que tem uma idéia muito clara de como seu código pode mudar no futuro, provavelmente deve pensar além de apenas fazer um comentário e incorporar esses parâmetros dentro do próprio código, pois quase sempre será uma maneira mais confiável de garantir a confiabilidade de versões futuras do seu código do que tentar usar comentários para orientar uma futura pessoa desconhecida na direção certa. Ao mesmo tempo, você também deseja evitar a generalização excessiva, já que os humanos são notoriamente ruins em prever o futuro, e isso inclui o futuro das mudanças no programa. Portanto, tente definir e capturar dimensões razoáveis ​​e comprovadas do futuro em todos os níveis do design do programa, mas não

No meu próprio código, deixarei com frequência tautologias de comentários, incluindo as particularmente notórias, como:

<?php
// return the result
return $result;
?>

... que obviamente contribuem pouco em termos de tornar o código mais compreensível de uma perspectiva explicativa.

Na minha opinião, porém, esses comentários ainda têm valor, se ajudarem a manter a consistência visual dos padrões de cores em seu marcador de sintaxe .

Penso no código como tendo uma estrutura muito semelhante ao idioma inglês, na medida em que existem "sentenças" e "parágrafos" (mesmo que um "parágrafo" possa consistir inteiramente em uma única "sentença"). Normalmente, incluo um resumo de quebra de linha e uma linha acima de cada "parágrafo". Por exemplo:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ignore o código incompleto, as injeções de SQL, etc. Você entendeu.)

Para mim, o comentário final realmente agrega valor ao código, simplesmente porque ajuda a delinear visualmente um "parágrafo" de outro, mantendo um esquema de cores consistente.

Os comentários devem ser usados ​​para executar um dos seguintes procedimentos.

1. Informações para geradores de documentos. Isso não pode ser subestimado, isso é extremamente importante.
2. Avisos sobre por que um pedaço de código é o que é e quais outras considerações. Eu lidei com o código escrito em 2 linguagens de programação. Uma parte importante disso era ter uma estrutura comum entre os dois idiomas. Um comentário nos dois locais informando ao usuário que, se alterar esse número, ele também precisará alterar outro, é extremamente útil.
3. Escreva notas para explicar por que um código particularmente estranho é o que é. Se você tiver que pensar em como fazer com que um pedaço de código funcione de uma maneira específica, e a solução não seja evidente desde o início, provavelmente vale uma explicação sobre o que você estava tentando fazer.
4. Rotular entradas / saídas, se não estiverem claras. É sempre bom saber quais são as suas entradas e em que formato elas estão.

Os comentários não devem ser usados ​​para fazer o seguinte:

1. Explique coisas extremamente óbvias. Eu código serra legado uma vez assim: page=0; // Sets the page to 0. Eu acho que qualquer indivíduo competente poderia descobrir isso.

Eu removeria a tautologia, mas manteria o comentário, comentaria propriedades e nomes de variáveis, fornecendo um valor de amostra, para que o uso seja claramente entendido:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Agora eu sei exatamente o que se passa lá e, pelo comentário, tenho uma ideia clara de como usá-lo.

Eu diria que depende do objetivo dos comentários.

Se eles devem ser usados ​​para gerar documentação para uso da equipe que a constrói (ou se são apenas comentários embutidos para explicar as coisas), acho aceitável deixar isso de fora. Pode-se supor com segurança que é auto-explicativo; e quando não é, existem outros membros da equipe por perto que podem explicar. Obviamente, se isso não for evidente para muitas pessoas, você deve adicioná-lo.

Se os comentários gerarem documentação para uma equipe geograficamente distante, eu colocaria toda a documentação lá.

Eu acho que esse tópico foi discutido bastante extensivamente sob nomes como "comentários: anti-padrões" ou "os comentários têm cheiro de código?" ( um exemplo ).

Costumo concordar com a ideia geral de que os comentários devem adicionar novas informações, e não duplicadas. Ao adicionar comentários triviais como esse, você está violando DRY e diminuindo a relação sinal / ruído do código. Costumo encontrar comentários de alto nível explicando as responsabilidades, a lógica por trás e o exemplo de uso da classe muito mais útil do que os comentários por propriedade (especialmente os supérfluos).

Pessoalmente, no seu exemplo, eu deixaria um comentário de fora (se realmente não houver nada útil a acrescentar sobre a propriedade).

Se você pode escrever um código que não exija comentários, você conseguiu programar o nirvana !.

Quanto menos comentários seu código exigir, melhor o código!

Um comentário como esse é inútil; O que estou fazendo errado?

Só parece inútil se você já sabe o que UpdateLocationfaz. "Update" aqui é um verbo ou um substantivo adjunto? Ou seja, isso é algo que atualiza o local ou é o local da atualização? Pode-se inferir o último do fato de que UpdateLocationaparentemente é uma propriedade, mas o ponto mais importante é que às vezes não custa declarar explicitamente algo que parece óbvio.

À parte a documentação compilada automaticamente, o código deve se documentar, de modo que os comentários devem documentar apenas onde o código não é suficiente para se documentar.

"Localização" é meio óbvio, mas "Atualização" pode ser um pouco vago. Se você não pode escrever um nome melhor, pode oferecer mais detalhes no comentário? Atualização de quê? Por que nós precisamos disso? Quais são algumas suposições (é nulo permitido)?