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

Na maioria dos projetos em que trabalho, não há tempo significativo para escrever comentários detalhados em cada um dos alunos.

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

Especialmente considerando o uso de comentários pelo 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 quando você continuar a codificar, quando não conseguir lembrar se UpdateLocation foi o local em que a atualização ocorreu ou o local para o qual a atualização está sendo enviada, ' Teremos que revisitar 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 algum outro programador perguntar detalhes sobre um campo, atualize os comentários com essa informação:

What sort of update should Example.UpdateLocation be used to store?

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 na compreensão do código quando você o revisitar seis meses depois e não se lembrar de nada sobre como o programa funciona.

E, assim como a programação, seus comentários precisam começar em algum lugar. Comentários tautológicos são o Hello World! de comentários, enquanto você pratica a escrita e a atualização da documentação, sua documentação inicial se tornará cada vez mais resiliente.

Os comentários devem nunca duplicar seu código. Os comentários não devem responder à pergunta " como? ", mas apenas " por quê? " e " o quê? ". Por que tal algoritmo é escolhido, quais são as suposições implícitas aqui (a menos que sua linguagem seja poderosa o suficiente para expressá-la com sistema de tipos, contratos e similares), o que é uma razão para fazer essa coisa, etc.

Eu recomendaria dar uma olhada na prática de Programação Literata para uma inspiração.

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

Deixe-os de fora!

Normalmente, é uma boa prática remover comentários quando as informações expressas neles já estiverem presentes em outro lugar. Se você puder expressar o objetivo de um método de forma clara e inequívoca, dando-lhe um bom nome, então existe não há necessidade de um comentário .

Coloque-os!

Seu exemplo ilustra duas exceções a essa 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 ambigüidade. Melhorar o nome geralmente é a melhor opção, mas isso nem sempre é possível (quando você está implementando uma API publicada, por exemplo).

Em segundo lugar, o "///" em C # indica um comentário que deve ser usado para gerar automaticamente a documentação. O IDE usa esses comentários para dicas de ferramentas e há 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 se os métodos que eles já documentarem tiverem 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.

Eu discordo strongmente 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á ambigüidade. Um recém-chegado 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 significa "local de atualização" e não "atualiza a localização". 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 nisso apenas por economizar alguns segundos do seu tempo.

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

Assim, se esta for uma API voltada ao público, você deve sempre incluir pelo menos um comentário <summary> , mesmo que o propósito da função seja -evidente para os leitores.

No entanto, esta é a exceção à regra; em geral, lembre-se de DRY (Não se Repita) .

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

_{Para mim, o caso de benefício claro foi quando houve uma verificação automática de comentários ausentes e Eu estava usando essa verificação para detectar códigos onde informações importantes eram necessárias ser preenchido; para isso, eu estava realmente preenchendo alguns espaços reservados - apenas para garantir que o relatório da ferramenta não contenha "alarmes falsos".}

Eu acho que sempre há uma maneira de evitar duplicação flagrante . Com o passar dos anos, usei "preenchimentos de modelo" para casos como o seu - principalmente como nome descritivo e veja acima .

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

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

_{Exemplo de quando eu poderia usar os preenchedores acima seria comentários do Javadoc que exigem campos dedicados para o valor de retorno, parâmetros e exceções. Com muita frequência, acho que faz mais sentido descrever a maioria ou até mesmo todas essas frases em uma única frase, método que retorna < descrever o que é retornado > para parâmetros fornecidos < descrever parâmetros > . Em casos como esse, preencho os campos formalmente obrigatórios com plain veja acima , apontando o leitor para a descrição resumida.}

Eis uma pergunta que gosto de fazer a mim mesmo quando penso em adicionar um comentário em uma seção do código: O que posso transmitir para ajudar a próxima pessoa a entender melhor a intenção do código , para que eles possam atualizá-lo, corrigi-lo ou estendê-lo de maneira mais rápida e confiável?

Às vezes, a resposta correta para essa pergunta é que não há nada que você possa adicionar nesse ponto do código, porque você já selecionou nomes e convenções que tornam a intenção tão óbvia quanto possível. Isso significa que você escreveu um código sólido de autodocumentação e que inserir um comentário provavelmente prejudicaria mais do que ajudaria. (Observe que comentários redundantes podem realmente danificar a confiabilidade do código ao longo do tempo, diminuindo a falta de sincronia com o código real ao longo do tempo e, assim, dificultando a decifração da intenção real.

No entanto, em praticamente qualquer programa e em qualquer linguagem de programação, você encontrará pontos em que certos conceitos críticos e decisões tomadas pelo programador original - por você - não serão mais aparentes no código. Isso é praticamente 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 todos os seus muitos futuros consertos e versões e extensões e modificações e portas e quem sabe o que também funciona corretamente. Esse último conjunto de metas é muito mais difícil e requer muito mais raciocínio para fazer bem. Também é muito difícil expressar bem na maioria das linguagens de computador, que são mais focadas na funcionalidade - isto é, em dizer o que esta versão do programa precisa fazer, agora, a fim de torná-lo satisfatório.

Aqui está um exemplo simples do que quero dizer. Na maioria das linguagens, uma pesquisa rápida na linha de uma pequena estrutura de dados terá complexidade suficiente para que alguém que a analise 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 tardio provavelmente apreciará imediatamente como útil para decifrar os detalhes.

Por outro lado, em linguagens como a linguagem baseada em lógica Prolog, expressar a busca de uma lista pequena pode ser tão incrivelmente trivial e sucinto que qualquer comentário que você possa adicionar seria apenas ruído. Então, bons comentários são necessariamente dependentes do contexto. Isso inclui fatores como os pontos strongs da linguagem que você está usando e o contexto geral do programa.

A questão é a seguinte: 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 as partes do seu código que são realmente auto-documentadas, os comentários adicionam ruído e aumentam o problema de coerência para versões futuras. Então 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 próprio código é complexo o suficiente para que seu propósito seja obscuro, por favor, adicione seu conhecimento especial na forma de um comentário. Um bom comentário, nesse caso, é aquele que permite a algum futuro programador saber o que deve ser mantido o mesmo - esse é o conceito de uma afirmação invariável, aliás - e o que é certo mudar.

[1] Isso vai além da questão dos comentários, mas vale a pena mencionar: se você perceber que tem uma ideia muito clara de como seu código pode mudar no futuro, provavelmente pensará além de apenas fazer um comentário e embutir esses parâmetros dentro do código em si, já que quase sempre será uma maneira mais confiável de garantir a confiabilidade de futuras versões do seu código do que tentar usar comentários para orientar uma pessoa futura desconhecida na direção certa. Ao mesmo tempo, você também quer 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 captar dimensões razoáveis e comprovadas do futuro em todos os níveis do design do programa, mas não deixe que isso o distraia em um exercício de generalização excessiva que é improvável que se pague a longo prazo.

No meu próprio código, freqüentemente deixo comentários de tautologias, incluindo os mais notórios como:

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

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

Na minha opinião, no entanto, 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 .

Eu penso no código como tendo uma estrutura que é muito semelhante ao idioma inglês, em que há "sentenças" e "parágrafos" (mesmo que um "parágrafo" possa consistir inteiramente em uma única "sentença"). Eu geralmente incluo um resumo 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 SQL, etc. Você tem a idéia.)

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

Os comentários devem ser usados para realizar uma das ações a seguir.

1. Informações para geradores de documentos para pegar. Isso não pode ser subestimado, isso é extremamente importante.
2. Avisos sobre o motivo pelo qual uma parte do código é do jeito que é e quais outras considerações. Eu lidei com código escrito em 2 linguagens de programação. Uma parte fundamental disso era ter uma estrutura comum entre os dois idiomas. Um comentário em ambos os locais informando ao usuário que, se eles alterarem esse número, eles também precisarão alterar outro é extremamente útil.
3. Escreva notas para explicar por que um código de aparência particularmente esquisito é como é. Se você tivesse que pensar em como fazer um trecho de código funcionar de uma maneira particular, e a solução não é evidente desde o começo, provavelmente vale a pena 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 que são extremamente óbvias. Uma vez vi um código legado como este: page=0; // Sets the page to 0 . Eu acho que qualquer pessoa competente poderia descobrir isso.

Eu removia a tautologia, mas mantinha o comentário, eu comentava propriedades e nomes de variáveis, dando um valor de amostra, para que o uso fosse claramente entendido:

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

Agora eu sei exatamente o que acontece lá e, a partir do comentário, tenho uma ideia clara de como usá-lo.

Eu diria que isso depende do propósito dos comentários.

Se eles forem usados para gerar documentação para uso da equipe (ou se forem apenas comentários inline para explicar as coisas), então acho aceitável deixar isso de lado. Pode-se supor com segurança que é autoexplicativo; e quando não é, há outros membros da equipe por perto que podem explicá-lo. Claro, se não for auto-evidente para muitas pessoas, você deve adicioná-lo.

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

Eu acho que este tópico foi discutido bastante extensamente sob nomes como "comentários: anti-padrões", ou "os comentários são um cheiro de código?" ( um exemplo ).

Eu costumo concordar com a ideia geral de que os comentários devem adicionar novas informações, não duplicadas. Adicionando comentários triviais como esse, você está violando DRY e diminuindo a relação sinal / ruído do código. Tenho a tendência de 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, deixo comentários para fora (se realmente não há nada útil para adicionar sobre a propriedade).

Se você pode escrever código que não requer comentários, então você alcançou o nirvana de programação!.

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

A comment like that is useless; what am I doing wrong?

Só parece inútil se você já sabe o que o UpdateLocation faz. É "atualizar" 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 a partir do fato de que UpdateLocation é aparentemente uma propriedade, mas o ponto principal é que às vezes não faz mal afirmar explicitamente algo que parece óbvio.

Documentação auto-compilada à parte, o código deve documentar-se, para que os comentários só documentem onde o código não é suficiente para se documentar.

"Localização" é óbvia, mas "Atualizar" 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)?