36

Passei pelas linguagens PHP, C, C++, JavaScript e agora estou trabalhando com C#. Nesse tempo todo sempre ouvi dizer que é importante ter códigos bem comentados, mas eu nunca soube a medida certa de comentários. Ou comento de mais ou comento de menos.

Além disso, no C# tem aquele comentário com três barras que basicamente gera algo assim

/// <summary>
/// 
/// </summary>
/// <returns></returns>

E ainda tem um comentário que normalmente alguns programadores colocam no topo do código com várias informações como nome do programador, data, versão, etc.

Dessa forma, qual a medida certa de comentários para que eles ajudem na compreensão do código invés de simplesmente poluí-lo?

2
  • Se eu tivesse dando manutenção neste código o que gostaria de ver comentado !?
    – Motta
    Commented 11/05/2014 às 1:08
  • 1
    De acordo com a resposta do @Bigown alguns usuários deveriam por crédito ao SOpt no cabeçalho do código, e não no corpo. (vide a parte que menciona ética) :)
    – Largato
    Commented 13/05/2014 às 2:43

3 Respostas 3

30

Terminei meu mestrado esse ano, e um dos meus dois orientadores, profundo conhecedor de design patterns, UML e OO, pregava que excesso de comentários ao longo do código poderia ser um indício de algo mais sério como um bad smell.

De acordo com ele, explicar resumidamente o que o método faz (por exemplo, antes do método) está OK. Contudo, comentar muitas linhas de código dentro do método, como já disse, pode indicar que algo está errado, ou pode indicar até mesmo uma gambiarra.

Por exemplo, um caso que ele citava bastante (ele não utilizava esse código em específico, mas a ideia é o que conta):

public void FinalizarPedido(...) {
    //Verifica se o desconto não passa de 20% do valor total do pedido
    if (descontoEmReais > valorDoPedido * 0.2f) {
        //Erro, desconto maior do que o permitido
        <CÓDIGO A>
    }
    <CÓDIGO B>
}

De acordo com ele, o fato de você ter que comentar a linha antes do if e o código dentro do if, significa que seu código não está compreensível o suficiente pra outra pessoa. Ou seja, o código acima poderia ser substituído por algo parecido com o código abaixo, de modo a remover a necessidade dos comentários:

private const float PercentualMaximoDeDesconto = 0.2f;

public float DescontoMaximo {
    get { return valorDoPedido * PercentualMaximoDeDesconto; }
}

public bool DescontoEValido {
    get { return (descontoEmReais <= DescontoMaximo); }
}

public void FinalizarPedido(...) {
    if (!DescontoEValido) {
        <CÓDIGO A>
    }
    <CÓDIGO B>
}

Ao longo de todo meu mestrado ele sempre afirmava isso:

"Criar um código que uma máquina entenda é fácil, difícil é criar código que outra pessoa entenda"

Não sei se essa frase é dele, ou é de outra pessoa, inclusive se é de outro país. Como eu concordo com essa frase, nunca fui atrás para descobrir sua real origem.

*Um detalhe: todo o código que meu orientador fazia estava em Java. Adaptei para C# para adequar à pergunta.

Do outro lado está o caso de uma empresa onde trabalhei. Lá utilizava-se uma métrica que poderia ser entendida como Percentual de linhas de comentários como um indicador de código compreensível e bem documentado, para fins de auditoria etc.

Alguns arquivos chegavam a ter mais de 50% de linhas de comentários. Outros, quase 75% de comentários.

Contudo, aquele monte de comentários, na realidade, tinha um efeito bem diferente.

Além de atrapalhar a edição e a manutenção do código (que não ficava nem um pouco fluido de ser lido), a quantidade de comentários era tanta, que inconscientemente nós acabávamos "filtrando" os comentários na hora da leitura, e ninguém realmente lia o que estava escrito lá.

9
  • 3
    Excelente. Só um comentário sobre a conversão para C#: private readonly float PercentualMaximoDeDescosto = 0.2f; seria o correto em C#. A linguagem conceitua corretamente o que algo é constante e o que é apenas somente de leitura. O percentual não é constante. Ele apenas não muda durante a execução. PI é constante. E a outra coisa é que ALL CAPS não acrescenta nada e os desenvolvedores de C# preferem não poluir o código com algo tão feio. Havia um motivo para isso no C original. Assim como comentários, a motivação deixou de existir mas as pessoas continuaram usando sem saber porque.
    – Maniero
    Commented 11/05/2014 às 18:15
  • 4
    Não vou nem reclamar do percentual ser um float porque é apenas um exemplo. Mas só deixar claro para os desavisados que isso provavelmente será usado em cálculos monetários e pode gerar problemas de arredondamento.
    – Maniero
    Commented 11/05/2014 às 18:20
  • 3
    @Motta boa observação, isso é algo que faltou nas respostas até agora. Talvez possa colocar uma. Muitas vezes a explicação pode estar no cabeçalho, na documentação, o que deixa claro para os programadores e para o usuários do método com o que ele está lidando. Dá uma referência de onde vem aquilo. Diz o porque tem aquilo e não o que aquilo está fazendo. É adicionar algo relevante que não está e realmente não deveria estar no código. Como demonstrar um memo em código? :)
    – Maniero
    Commented 11/05/2014 às 19:42
  • 3
    Até aproveitei o exemplo em pt.stackoverflow.com/a/15512/101
    – Maniero
    Commented 11/05/2014 às 19:44
  • 3
    Gostei dessa resposta: pt.stackoverflow.com/a/15512/101 Saber a diferença semântica entre os dois valeu meu dia! :D Commented 11/05/2014 às 19:47
25

Documentação

Embora o exemplo postado chame oficialmente de comentário de documentação e tenha uma semântica de comentário mesmo, ou seja, o compilador em sua operação normal o ignora completamente, considere-o como documentação e não como comentário.

Documentação é importante? Claro. A não ser que esteja fazendo um protótipo, um script muito simples, ou algo descartável, documentação é fundamental.

Acredito que a única "polêmica" sobre o assunto é se membros privados de uma classe devem ser documentados também. Alguns vão dizer que sim, outros acharão que um comentário simples é suficiente, e alguns dirão que não precisa documentar o detalhe de implementação, que só a API pública deve ser documentada.

É provável que você tenha colocado o trecho de documentação só para ilustrar, mas para deixar claro, o que não pode é deixar da forma que está aí. Muitas pessoas deixam só o esqueleto da documentação sem conteúdo.

Eu acho o recurso da documentação com /// muito bom. Gostaria que a formatação fosse mais simples, provavelmente JSON, Markdown ou algo assim. Mas foi desenvolvida no momento que a Microsoft estava amando XML. Ainda assim é útil.

Tags

Você tem tags que ajudam bastante identificar o que a classe faz e como usá-la. Lembre-se que a documentação deve ajudar quem vai usar a classe. Que será você no futuro ou outro programador. A documentação, em parte carrega um pouco da especificação. De fato é possível até linkar para documentos extras para notas dessas especificação.

As tags possuem alguma semântica. O próprio compilador sabe interpretar essas tags e usam esses comentários no Visual Studio para informar melhor o programador no Intellisense, Object Browser, etc.

Você pode até mesmo criar tags personalizadas. Existem alguns softwares sofisticados para gerar saídas bem formatadas. Talvez o mais moderno e ativo atualmente seja o SandCastle (tem outros).

Embora possa colocar em qualquer lugar, acho que falta, por exemplo, uma tag <deprecated>. Talvez porque exista um atributo para identificar isso no código. Mas na tag você poderia explicar e indicar alternativa. Daria mais semântica que colocar em <remarks>.

Também não sofra da síndrome do canivete suíço. Ninguém é obrigado a usar todas as tags. Depende do que você está fazendo, um simples <summary> é suficiente. Em geral documentar os parâmetros e retorno também é necessário. Indicar exceções que o método pode gerar é importante.

Arquivo externo

É possível incluir a documentação vinda de um arquivo externo. Não acho esse recurso particularmente útil. O ideal é ter a documentação mais próximo possível do que ela está documentando. Se for para colocar em outro arquivo, então não precisa ter uma ligação. Talvez para facilitar o acesso ao arquivo, sei lá.

Mas também não é o fim do mundo usar um arquivo separado. Documentação costuma ser bastante estável. Ou seja, a não ser por melhorias no conteúdo você raramente mexe nela. Se está documentado só a parte pública da classe tem que ser assim, afinal depois que você criou uma classe, um método, você não pode sair mudando-o muito, sob risco de quebrar programas que estão usando-os. Se o contrato não muda, a documentação não muda.

Diferença entre documentação e comentário

Documentação documenta o contrato, não a implementação, não o código propriamente dito. Por isso é bom não chamá-la de comentário. Documentação diz o que a classe e o método faz em linhas gerais, ajuda eles serem usados.

Cabeçalho com autoria

Quando você olha a lista de tags que a Microsoft criou para você usar, você encontra autor ou data de criação? Não.

Tem uma boa razão para isso. Este tipo de informação deve estar no controle de versão. Isso será armazenado no SVN, no Git, no Mercurial, no TFS, etc. Use a ferramenta certa para controlar autoria. Nunca use cabeçalho de métodos para isso. Com o tempo você perceberá que é contraprodutivo e/ou que ninguém respeita isso.

Tem recomendações que perduram mais do que deveriam. O que vou dizer a seguir vale para muitas recomendações sobre estilo de codificação. As pessoas precisam saber o porquê de uma recomendação. Quando as pessoas aprendem só a recomendação elas não sabem quando parar de usar.

  • Nos anos 60 tinha motivo para usar isso, o código era simples, não havia ferramentas melhores.
  • Nos anos 70 era algo bem útil ainda.
  • Nos anos 80 era aceitável como uma forma simples de documentar.
  • Nos anos 90 era tolerável, nem todos sabiam como fazer melhor, nem sempre havia recursos melhores disponíveis.
  • Neste século é inacreditável que ainda exista isso. E existe.

Exemplo real de uso errado

Trabalhei em um grande fornecedor se sistema ERP e este sempre foi o método de "documentar" o sistema. Tive acesso aos fontes mais recentes e continua assim. E pior, continua uma bagunça.

Raramente alguém atualiza o cabeçalho para indicar as alterações (apesar que eu não sei se isso é bom ou ruim neste caso), quando atualizam, é comum não colocar como alteração. Vi várias funções que eu sei que foram totalamnete desenvolvidas por mim com nome de outra pessoa porque ela trocou uma vírgula na função. Tudo bem, isso sempre foi a cultura lá. Mas já mostra que o cabeçalho de fato não serve para muita coisa. É pura burocracia sem sentido.

Imagine o que vale saber quem criou uma função 20 anos depois que ela saiu da empresa. A data de criação é tão relevante? Ou o histórico completo é que é? Versão? Versão do que? Do método? Quem controla isso? Versão da aplicação? Vai sair mudando em todos os lugares cada vez que muda a versão da aplicação?

Como saber o histórico real, que linhas foram alteradas, a sequência precisa, sem esquecer de nada? Só um software de controle de versão consegue isso. Nem perca tempo com este tipo de informação em código. E não falo só do autor, qualquer coisa que possa se tornar irrelevante ou que não seja fácil manter correto.

No código não importa "quem e quando". Estas informações devem estar no controle de versão.

Exceção

Existe um caso que o cabeçalho é admissível. Colocar informações legais, como copyright por exemplo. Existem casos que isso é útil ou até obrigatório de acordo com a licença do código. Normalmente é mais no cabeçalho do arquivo e não da classe ou método.

Comentando código

É aqui onde há mais discordância da medida certa.

Legado

Nos primórdios da programação a regra do "comente todo seu código" era muito importante. Muitos não sabem que as linguagens não tinham estruturas adequadas para expressar o código, não tinham funções, as variáveis tinham que ser curtas (2 caracteres!) e você tinha que buscar performance acima de tudo. Os comentários eram fundamentais para entender um programa. Existiam e ainda existem linguagens que nem variáveis têm. Em uma linguagem Assembly comentários extensivos continuam importantes, afinal estamos falando de uma linguagem quase ilegível.

Mas isso tudo mudou nas linguagens de alto nível. Hoje comentários quase não são necessários. Bom, C é uma linguagem que ainda precisa um pouco, mas mais pelo estilo comum que os programadores C costumam programar do que por limitação atual da linguagem. C costuma ser usado como um Assembly portável.

Exageros

Há quem ainda ache que comentários devem ser extensivos. Já pedi demissão de emprego que me obrigava fazer algo assim:

//Este método vai inicializar os componentes
InicializaComponentes();

Juro! Mas quem pensa sobre o assunto, hoje reconhece que comentários em código devem ser bem limitados. Comentários em código são mais difíceis de manter. Você está comentado o detalhe de implementação, isso pode mudar a qualquer momento.

Problemas

Convenhamos, ninguém gosta de comentar.

Há quem ache que um comentário desatualizado é melhor que nada, há quem ache que isso é pior que nada. Eu digo que varia de caso para caso. Não há como saber se vai ser pior ou melhor. Eu acho que o risco é menor não comentado algo.

O mais importante é que o código seja expressivo. Se ele foi bem pensado, e bem construído, o comentário se torna desnecessário. O código, e não o comentário, deve dizer como fazer.

O que deve conter nos comentários?

Comentários que dão referência de onde encontrar mais informações para entender a decisão, o algoritmo escolhido, ou que explique a fórmula adotada, são sempre muito apropriados. Em alguns casos essa referência pode estar na documentação, mas nem sempre.

  • Essa referência é detalhe de implementação? É comentário.
  • Faz parte do contrato? É útil para o consumidor da classe/método? É documentação.

Cuidado para não abusar disto. Muitas destas referências talvez caibam mais no controle de versão do que no código. Imagine colocar um comentário para cada ticket de bug que você resolveu. Isso vai na mensagem de commit do controle de versão.

Já um link para a resposta no SOpt onde você ganhou o algoritmo pronto é até questão de ética :D

Para tudo existe exceção. Indicar um ticket para mostrar um bug que deve ser evitado em futuras alterações é uma boa. Você está explicando o porque de ter adotado um caminho que não parece ser o melhor à primeira vista.

Comentário semântico

Alguns comentários podem ter semântica. Ex.: //TODO: xxx, //TOFIX: yyy, //HACK: zzz. Existem ferramentas que te alertam para alguns deles. Isso ajuda você não esquecer que algo ainda precisa de trabalho. O problema é que as pessoas os ignoram. Quando esses comentários duram muito tempo eles perdem a vantagem.

Melhorando o código antes de comentar

Não vou detalhar aqui o que já foi dito em outras respostas, mas mantenha nomes significativos para tudo, métodos curtos que façam apenas uma tarefa, mantendo o mesmo nível de abstração dos demais.

Resumo

Existem algumas dicas para definir quando comentar:

  • diga porque o código está ali e não o que ele faz;
  • não use } //if (cond), se isso é necessário, seu if está muito grande (ou while, for, etc.);
  • evite deixar código commented out, código que não deve ser executado mais (na versão final antes do commit, no momento que está mexendo, ok);
  • seja muito sucinto;
  • se o código precisa de comentário, ele pode estar complexo demais (a não ser que o domínio seja complexo);
  • comentários são bons para explicar código que ficou "sujo" por necessidade de otimização;
  • evite surpresas que o programador pode ter, explicando o que está por vir (algo que pode ser um WTF), alerte para e amplifique consequências ou workarrounds usados;
  • evite redundância, mas use quando for realmente útil, pense antes de escrever;
  • explique a intenção do código quando não é óbvia e não é possível mostrar isso em código de forma simples;
  • os comentários devem ser simples, não os enfeite;
  • se a informação do comentário é muito grande, talvez ele deva estar em uma nota externa;

Existem pessoas que preferem ter algumas tags definidas para dar semântica ao comentário (HACK, REF, TOFIX, SECURITY:, etc). E quando nenhuma tag parece ser adequada, é sinal que o comentário não deveria estar ali.

Não se esqueça que qualquer regra pode e deve ser quebrada para obter um resultado melhor. A experiência qualitativa ajuda decidir isso. Não esqueça também que algumas pessoas discordarão de boa parte destas regras.

Referências

Exitem estudos sérios sobre o assunto. O difícil é achar :)

Alguns livros que podem ajudar ou atrapalhar você (lembra do emprego que pedi demissão? Meu chefe era fã desses livros):

  • Code Complete - Steve McConnell
  • The Pragmatic Programmer - Andy Hunt and Dave Thomas
  • Clean Code: A Handbook of Agile Software Craftsmanship - Robert "Uncle Bob" Martin

Por exemplo, um destes livros, que é quase uma unanimidade entre programadores, é opinativo, confuso, impreciso, e especialmente contraditório, ou seja, parece horóscopo. Ele fala algo ótimo para uma linguagem e péssimo para outras. Mas não diz quando deve usar. Aí as pessoas generalizam. Não explica porque usar várias recomendações. Mesmo quando explica, o programador inexperiente não entende quando o argumento dele é ruim. Também não estou dizendo que o livro não serve para nada.

Coloquei no GitHub para referência futura.

12

Um problema sério que já tive com excesso de comentários, é que nem sempre todos os programadores que participam de um projeto são tão metódicos a ponto de alterar os comentários quando o código muda, e esse problema é agravado ao passo que se aumenta a quantidade de comentários.

Com uma quantidade de comentários reduzida, é possível manter a coerência do código, mas é necessário que o código seja auto-explicativo (vide resposta do @carlosrafaelgn), de forma que possa ser compreendido, não só por outros programadores, mas até por você mesmo. Eu já me esqueci do que um código feito por mim fazia, e para entender é necessário que o código seja claro. Somente quando isso não for possível, se deve colocar comentários no código.

Se a quantidade de comentários for justificável, fica mais fácil convencer a todos da equipe a fazer a manutenção dos comentários que existem, pois será menos trabalhoso.

No C#, ainda há um tipo de comentário que eu recomendo fortemente, que é o de documentação. Esses comentários são extremamente úteis, pois fornecem meios para as ferramentas documentarem o código de forma descritiva para que for usá-lo como biblioteca, ou seja, como uma caixa preta, sem ter de conhecer o código fonte do método que está sendo chamado.

/// <summary>
/// Classe que representa uma lista de pessoas, e contém métodos para manipular
/// todas as pessoas e obter resultados sobre todas as pessoas como um conjunto.
/// Essa classe pode ser usada no contexto Xpto quando é necessário
/// passar registros de pessoas de um local X para outro Y, pois permite fazer serialização.
/// </summary>
public class ListaDePessoas : List<Pessoa> { ... }

A utilidade desses comentários de documentação está na descrição do que o elemento sendo documentado faz. Não adianta nada colocar um comentário desses, dizendo exatamente o mesmo que o nome da entidade documentada já diz.

/// <summary>
/// Classe que representa uma lista de pessoas.
/// </summary>
public class ListaDePessoas : List<Pessoa> { ... }

O comentário acima é inútil.

8
  • 5
    A resposta é muito boa. Mas para contrapor e mostrar como comentário tem muito de gosto, se eu tivesse feito o primeiro parágrafo seria "Representa uma lista de pessoas, podendo manipular e obter resultados sobre todas as pessoas como um conjunto.". O exemplo nem é o melhor, mudou pouco, mas o que queria mostrar é que comentários também podem passar do ponto. De qualquer as duas respostas até agora são complementares e foi bom todo mundo se segurar para fechar a pergunta porque dava para ter respostas.
    – Maniero
    Commented 11/05/2014 às 18:30
  • Outro ponto é que nem todos os programadores tem o mesmo nível de conhecimento na linguagem , óbvio para um sênior é exotérico para o júnior. Existe uma norma da ABNT sobre comentários em códigos, creio, mas não lembro qual agora.
    – Motta
    Commented 11/05/2014 às 19:40
  • 3
    @Motta Essa ABNT seria muito útil aqui. Tomara que alguém saiba qual é a norma.
    – Maniero
    Commented 11/05/2014 às 19:45
  • @bigown , não estou certo dela, um programador com que trabalhei dizia seguir esta norma, mas estas normas são pagas e acabei não comprando.
    – Motta
    Commented 11/05/2014 às 19:51
  • @bigown: o comentário de documentação ficou muito ruim em termos de conteúdo no primeiro exemplo, entretanto, foi por falta de imaginação mesmo... o que eu quis dizer é que comentários de documentação devem ser mais do que triviais, apontando detalhes mais importantes, tal como restrições de uso, e outras coisas que o programador que utiliza geralmente esquece ao usar uma classe ou um método. Digo isso, pois esses comentários são bem "acessíveis" assim por dizer, através das ferramentas, tal como o Visual Studio, que mostra o comentário ao passar o mouse sobre o nome da entidade documentada. Commented 12/05/2014 às 13:08

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .