13

Ao trabalhar em grupo, desenvolvendo códigos com outras pessoas, utilizando ferramentas especificas e tudo, qual a melhor forma de comentar o código?

Bom, vamos ao cenário.

Ao possuir o projeto no Subversion, Mercurial, Git, TFS, ou outras ferramentas, onde vários colaboradores terão acesso para desenvolver o projeto. Ao analisar o código que outra pessoa desenvolveu, podemos observar que alguns são ótimos profissionais, com tudo padronizado. Porém, sempre existe POG's (Programadores Orientados a Gambiarra) que deixam o código todo desorganizado, e dificultando o entendimento do mesmo. Partindo daí, me vem a dúvida: Comentar o código ajuda, mas como realizar estes comentários de códigos?

Ao trabalhar com diversos programadores, pode-se observar que cada um realizar comentários, como "pensa" ser a melhor forma, isso quando o projeto não possui um padrão.

Vou utilizar este código para demonstrar algumas formas:

#include <iostream>
#include <string>

 using namespace std;

 class Person 
 {
   string name; 
   int height;
 };

 void setValues(Person&);
 void getValues(const Person&);

 int main ()
 {
   Person p1;
   setValues(p1);  
   cout << "Informando dados sobre a pessoa:\n";
   cout << "================================\n";
   getValues(p1);
   return 0;
 }

 void setValues(Person& pers)
 {
   cout << "Informe o nome da pessoa: ";
   getline(cin, pers.name);
   cout << "Informe a altura em milímetros: ";
   cin >> pers.height; 
   cin.ignore();
 }

 void getValues(const Person& pers)
 {
   cout << "Nome da pessoa: " << pers.name << endl; 
   cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
 }

Comentar o código no início da classe, onde coloca-se a funcionalidade de uma classe, e seus métodos irão realizar.

#include <iostream>
#include <string>

 //Classe responsável por realizar o get, set de uma pessoa
 using namespace std;

 class Person 
 {
   string name; 
   int height;
 };

 void setValues(Person&);
 void getValues(const Person&);

 int main ()
 {
   Person p1;
   setValues(p1);  
   cout << "Informando dados sobre a pessoa:\n";
   cout << "================================\n";
   getValues(p1);
   return 0;
 }

 void setValues(Person& pers)
 {
   cout << "Informe o nome da pessoa: ";
   getline(cin, pers.name);
   cout << "Informe a altura em milímetros: ";
   cin >> pers.height; 
   cin.ignore();
 }

 void getValues(const Person& pers)
 {
   cout << "Nome da pessoa: " << pers.name << endl; 
   cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
 }

Comentar somente os métodos, descrevendo a funcionalidade de cada um, porém não se aprofundando em cada método.

#include <iostream>
#include <string>


 using namespace std;

 class Person 
 {
   //Declara as variáveis
   string name; 
   int height;
 };

 //get set da classe
 void setValues(Person&);
 void getValues(const Person&);

 //método para receber dados da pessoa
 int main ()
 {
   Person p1;
   setValues(p1);  
   cout << "Informando dados sobre a pessoa:\n";
   cout << "================================\n";
   getValues(p1);
   return 0;
 }

 //realiza o set da pessoa
 void setValues(Person& pers)
 {
   cout << "Informe o nome da pessoa: ";
   getline(cin, pers.name);
   cout << "Informe a altura em milímetros: ";
   cin >> pers.height; 
   cin.ignore();
 }

  //realiza o get da pessoa
 void getValues(const Person& pers)
 {
   cout << "Nome da pessoa: " << pers.name << endl; 
   cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
 }

Comentando todas as funções do código:

#include <iostream>
#include <string>

//Classe responsável para guardar e mostrar nome e altura de uma pessoa
 using namespace std;

 class Person 
 {
   //Declara as variáveis
   string name; 
   int height;
 };

 //get set da classe
 void setValues(Person&);
 void getValues(const Person&);

 //método para receber dados da pessoa
 int main ()
 {
   //instancia a classe
   Person p1;
   setValues(p1);  
   cout << "Informando dados sobre a pessoa:\n";
   cout << "================================\n";
   getValues(p1);
   return 0;
 }

 //realiza o set da pessoa
 void setValues(Person& pers)
 {
   cout << "Informe o nome da pessoa: ";
   //Guarda o nome da pessoa
   getline(cin, pers.name);

   cout << "Informe a altura em milímetros: ";
   //Guarda a altura da pessoa em milímetros
   cin >> pers.height; 
   cin.ignore();
 }

  //realiza o get da pessoa
 void getValues(const Person& pers)
 {
   //retorna o nome da pessoa
   cout << "Nome da pessoa: " << pers.name << endl; 
   //retorna a altura da pessoa em milímetros
   cout << "A altura da pessoa em milímetros é: " << pers.height << endl;
 }

Podemos ver, que no último fica mais fácil compreender, porém o código ficaria mais extenso, levando em conta classes que contenham muitos métodos.

Eu postei somente alguns exemplos, porém já observei casos de comentários linha à linha, todas as propriedades de classes, mesmo comentário em classe e interface, dentre muitos outros.

A partir desse cenário, vem a minha dúvida: Existe uma forma "padrão" de boas práticas para comentar um código? Se não, qual a melhor forma?

Obs.: Analisei esta questão Aqui, no SOpt, porém ela está voltada para a linguagem C# e as Tags, de comentários, utilizas pela Microsoft. Minha dúvida é em relação as diversas linguagens, incluindo o próprio HTML simples.

1
  • 4
    Acho que padrões em comentários nos códigos serve para documentar e não necessariamente para trabalhar em grupo
    – Syzoth
    Commented 2/04/2015 às 14:55

3 Respostas 3

15

Regra de Ouro

Comentários devem ser evitados sempre que possível.

Como não precisar comentar

Uma das formas é adotar padrões ou convenções que facilitem a leitura do código.

Por exemplo, a primeira coisa que eu faria no seu código de exemplo é colocar a classe Person em um arquivo fonte person.cpp contendo apenas a classe. um diretório entities, model, domain ou equivalente contendo somente classes de domínio é auto-explicativo. Organize suas classes, funções e outros elementos de código em uma estrutura de diretórios que seja auto-explicativa.

O mesmo vale para nomenclatura das classes. Por exemplo, adicionando sufixos ou prefixos de acordo com padrões conhecidos: Dao, Repository, Helper, View, Controller, Business, Service, etc.

Nos métodos, utilize nomes descritivos. Métodos de acesso (getters e setters) não precisam de comentários. Procure escrever a maior parte do seu código principal em classes, pois isso facilita a organização e o entendimento. Por exemplo, chamar um método carregar_dados(file) não é tão claro, mas Person.carregar_dados(file) é intuitivo para carregar os dados da pessoa a partir de um arquivo.

Não use comentários contra intuitivos

Não confie em comentários para esclarecer um código contra intuitivo. Se uma classe, um método, uma função ou uma variável está com nome ruim ou um trecho de código está mal implementado, refatore para deixar mais claro.

Comentários como o abaixo até explicam o que o código faz:

//método para receber dados da pessoa
int main ()

Mas main para receber dados da pessoa? Aliás, esse comentário é enganador (como a maioria dos comentários que tentam "explicar" métodos. O main "recebe" os dados, imprime um cabeçalho e dois imprime os dados do usuário.

Não seria bem mais intuitivo e organizado algo como abaixo?

int main() 
{
    Pessoa p;
    receberDadosPessoa(p);
    imprimirCabecalho();
    imprimirDadosPessoa(p);
}

Precisa explicar o que o código acima faz?

Não ensine a programar com comentários

Se programadores mais novos não sabem como fazer as coisas na linguagem, faça um breve treinamento, programa em pares, etc. O pior lugar para ensinar alguém a programar é através de comentários no código.

Note o exemplo abaixo:

//Declara as variáveis
string name; 
int height;

Ou ainda:

//instancia a classe
Person p1;

Algo interessante nesse tipo de comentário é que o programador novato, que tem certo receio do que está fazendo, o coloca em dois ou três trechos, mas logo ele acha que não é mais necessário e esquece. Então o código acaba com alguns comentários aleatórios que são mais relacionados ao aprendizado e à insegurança do programador do que a alguma utilidade real.

Quando usar comentários

Use comentários principalmente nessas situações:

Explicitar regras de negócio que não são óbvias

Nem só de bits vivem os programadores. Algumas coisas fogem completamente ao nosso dia-a-dia e essas implementações precisam ser detalhadamente documentadas para evitar que um programador apressadinho tente "arrumar" algo que está correto.

Exemplo:

/*
 * Implementação segundo a fórmula do banco central disponível em [link]
 */
float converter_taxa_cdi_mensal_para_anual(...) 
{
    //padrão DU/252 representa o número de dias úteis
    //considerando-se um ano padrão de 252 dias úteis
    int diasUteisAno = 252;
    ... 
}

É tentador para qualquer bom programador achar que o número 252 fixo é uma gambiarra de alguém e que o código deveria, na verdade, calcular a quantidade de dias úteis do ano corrente.

Código genérico que também não tem sua função óbvia

Código genérico que implementa funcionalidade para ser reusada em determinados casos de uso precisa ser documentado de alguma forma para que os desenvolvedores saibam quando aplicá-lo sem precisar entender todo o seu funcionamento.

Exemplo:

/*
 * Implementa rotinas gerais usadas nas grids das telas que usam a biblioteca XPTO.
 * Facilita a ordenação automática.
 */
template<typename T> 
class ListaGenericaGrid
{ 
   ...
};

Trecho de código complexo, mas que tem uma razão de ser

Às vezes um trecho de código é difícil de ler, mas quem implementou tinha um motivo.

Veja um exemplo simples:

//x * 64, otimizado para o compilador XPTO
int x = y << 6;

A vantagem desse comentário é que se futuramente o "compilador XPTO" não for mais usado, qualquer programador poderá refatorar o código sem medo.

Referência a documentação externa

Às vezes é necessário fazer algo "estranho" à organização do código devido a algo externo ao seu programa.

Por exemplo, algumas vezes você usa uma biblioteca e precisa adicionar uma determinada funcionalidade. Então você estende uma classe e sobrescreve um método específico que não é óbvio. Nesse caso, vale a pena colocar um comentário para a documentação, tutorial ou bug tracker de onde essa ideia surgiu.

Considerações

A ideia é basicamente documentar com comentários apenas o que é relevante e não está explícito ou até certo ponto implícito no próprio código.

Principalmente, não comente o óbvio. É perda de tempo para quem escreve e para quem lê. É sujeira visual e tudo isso vai gerar, diretamente ou indiretamente, um custo maior para o projeto, seja em termos de dinheiro, tempo, complexidade, dificuldade de manutenção, etc.

2
  • 1
    O que você pensa sobre o Javadoc?
    – ptkato
    Commented 2/04/2015 às 16:55
  • @Patrick A maioria do que as ferramentas geram eu simplesmente apago. No entanto, a história muda completamente se a ideia for publicar uma API para terceiros. Quando vou publicar uma biblioteca, por exemplo, geralmente eu mantenho um documentação nas classes e nos métodos públicos explicando a forma de uso e dando exemplos.
    – utluiz
    Commented 2/04/2015 às 18:27
4

A maioria do que eu poderia dizer já foi dito nas respostas aqui e em minha resposta nessa pergunta. Leia também as outras respostas lá, de uma maneira geral concordo com elas. Não acho que o que foi exposto na pergunta citada sirva só para C#, alguns pontos sim, mas quase todos são universais.

Para consolidar e mostrar porque se prega o uso de comentários vou postar algo adicional.

Comentários não são bons porque eles ferem o DRY. Eles são difíceis de manter sincronizados. Comentários devem dizer porque algo foi feito e nunca o que foi feito ali.

Documentação

Não confunda comentários com documentação. Documentar as classes e métodos mesmo usando o mecanismo de comentários não devem ser interpretados como comentários. Esta documentação é mais fácil manter sincronizada com o código porque ela só documenta o contrato, e contratos não devem ser mudados. Mas se o contrato for mudado assim mesmo, certamente haverá muitos testes e precisará ser comunicado para todos os usuários. Certamente a mudança na documentação não será esquecida. E se for, sua equipe está toda lascada mesmo, entrega pra deus :)

Documentação deve fornecer informações relevantes. Leia a documentação de APIs conhecidas que têm fama de serem bem documentadas para ver o que é relevante. Colocar o óbvio não ajuda nada. Um comentário bobo só para dizer que documentou não serve para muita coisa. Deve haver explicação das implicações do uso daquela classe ou método. O que pode dar errado, quando usar e não usar. Porque aquilo existe, especialmente se parecer que não deveria existir. Documentar significa informar todos os aspectos daquilo, todos os dados importantes para o contrato, como parâmetros, retorno, exceções possíveis.

Para aprender só não vale olhar a documentação do PHP que é muito ruim :) Mentira, ela é melhor do que a maioria das documentações que as pessoas fazem. Ela só não é tão boa quanto algumas outras muito boas, que são exemplos de documentação bem feita. Embora nenhuma seja nota 10 também, documentar bem é difícil.

Mas também tem que ver o custo de documentar isto, nem sempre vale o esforço. Isto será muito grande? É muito complicado acompanhar sem documentação? Será que não dá para simplificar a arquitetura para evitar ter que documentar tanto? Muitas vezes não precisa de tudo o que foi feito. Dá para tornar privadas algumas partes e tirar da API? Será usado por muita gente? Por muito tempo?

Se linguagens de programação extremamente populares não fazem documentações nota 10 em suas APIs, porque você deveria fazer isto com seus sistema que será usado por uns poucos programadores? Pense nisto. E se não for para documentar razoavelmente bem, melhor nem documentar.

Códigos expressivos

Comentários de verdade só são necessários quando o código está mal escrito.

Comentários eram incentivados nos anos 50 e 60 quando as linguagens eram limitadas. Era comum variáveis só poderem ter 2 caracteres, funções nem existiam, ou também não podiam ter nomes expressivos. A memória era tão escassa que qualquer economia contava. O mesmo vale para ciclos de processamento. O importante era produzir código eficiente, até porque os compiladores eram bem ruins para otimizar. Legibilidade era secundária, tornando o comentário essencial. Na verdade onde mais se usava comentário era em Assembly - muito usado na época - que tem expressividade quase zero.

Isto foi ensinado para os recém-chegados na profissão. E eles se tornaram professores. Todos escreveram livros. E o conhecimento foi sendo passado para gerações. Mas a tecnologia mudou, as linguagens, os compiladores mais modernos e os recursos mais folgados permitiram preferir códigos legíveis e dispensar quase por completo o uso de comentários. Só que muita gente não percebeu isto. E continuam repetindo o mantra.

Você percebe que as pessoas tem dificuldades em comentar? Parece um fardo fazer isto. E é algo bem mais fácil e menos trabalhoso que codificar. Talvez, não tenho estudos sobre o assunto, seja porque subconscientemente as pessoas sabem que aquilo não serve para nada. Aí elas deixam de fazer quando o comentário é realmente necessário. O cérebro é muito confuso. Por isto propagandas usam esta falha para associar produtos com sentimentos bons. Por isto a gamificação funciona. Você tem que treinar seu cérebro para aceitar a importância dos comentários necessários e não deixar ele se confundir com a parte sábia dele que diz que comentário devem ser evitados.

Em alguma resposta ou comentário meu eu já critiquei o uso de comentários redundantes, como os usados no seu exemplo. Eu já pedi demissão porque eu era obrigado fazer isto:

//Este método inicializa os componentes
InicalizaComponentes();

Coloquei no GitHub para referência futura.

Note que é uma chamada, que é ainda pior documentar o uso. Se fosse na definição do método e explicasse porque ele é necessário, como ele age no sistema, aí tudo bem. Mas isto não só não era necessário, como não era feito por ninguém.

HTML e CSS

Mesmo HTML que não sendo muito expressivo, mas por outro lado também não gera tanta confusão, não é muito necessário. HTML não é uma linguagem de programação.

Se você organizar (com espaçamento vertical e horizontal) o código de forma à facilitar a fluência da leitura e se colocar nomes expressivos em id, class, name e outros atributos, eventualmente até colocando onde não são necessários naquele momento, também não precisa de comentário.

Eu vejo mais motivo para comentar código CSS. Ali tá cheio de gambiarras para funcionar em todos os navegadores. Tem que explicar porque está usando aquilo. Não tem como fazer código expressivo o suficiente para indicar porque aquela maluquice está ali. E nem precisa ser muito maluco para precisar de comentário.

Quase ninguém comenta CSS e quando comenta, em geral não é bem feito.

Conclusão

Uma coisa que eu aprendi é que a pessoa que não consegue programar direito não vai conseguir comentar direito. Por isto muitos comentários não só falam o óbvio mas fazem o oposto, falam coisas que não condizem com a realidade. Ela muitas vezes não entende o que ela está fazendo. Ela até sabe que o resultado está sendo produzindo mas ela não entende a semântica daquilo. E comentário, mesmo os que estamos dizendo que não são bons, servem para dar mais semântica ao que está sendo feito. Se o programador não sabe definir com clareza o que ocorre de fato ali, o comentário sairá errado. Eu mesmo depois de mais de 35 anos de experiência tenho dificuldades de entender totalmente o problema que estou lidando quando é um problema novo para mim. Um exemplo de como é fácil entender errado uma coisa pode ser vista em mais uma excelente resposta do Eric Lippert.

Eu não sei como resolver isto a não ser treinar bastante e talvez procurar ajuda profissional específica para ajudar na capacidade cognitiva.

2

Bom, sou totalmente contra comentários em códigos, porém como você mesmo informou sempre tem os movidos a gambiarra e consequentemente para gambiarra não existe convenção.

Comentários demais como na última opção são muito complicados, pois toda a vez que alterar alguma coisa no código terá que lembrar de verificar se o comentário deve ser atualizado também.

A melhor opção ficaria a de: Comentar somente os métodos, descrevendo a funcionalidade de cada um, porém não se aprofundando em cada método.

Preferencialmente utilizando a forma de comentário de múltiplas linhas:

/*
 * Método para receber dados da pessoa
 * Comentários assim permitem que os orientados 
 * a gambiarra tenham mais liberdade para quebrar linhas
 * e não extrapolar no comprimento, fazendo utilizar a 
 * barra de rolagem para que você possa ler
 */
int main ()
{
   //instancia a classe
   Person p1;
   setValues(p1);  
   cout << "Informando dados sobre a pessoa:\n";
   cout << "================================\n";
   getValues(p1);
   return 0;
}

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 .