Comentários em seus programas.

Um dos maiores problemas em qualquer código fonte são os comentários. Parece que os programadores de hoje em dia acreditam que todos que vão ler seus códigos sabem no mínimo tanto quanto ele, e na maioria das vezes sabem muito mais do que ele, porém não é bem assim que funciona.

Mesmo que você goste de programar sem documentação nenhuma, comentários devem existir e serem o mais claro possível, tentando sempre explicar seu algoritmo e não peculiaridades da linguagem, a não ser que seja coisas um tanto quanto escondidas, como por exemplo:

if(strncmp(“teste”,buff)==0) //Utilizamos ==0 para garantir que o if funcionará de forma esperada

Se tivéssemos retirado o “==0″ o if não funcionaria como esperado, apesar de estranho, já me peguei perdendo o sono por causa disso, esses comentários são bem vindos, agora um comentário assim:

if((buff=(char*)malloc(sizeof(char)*100))==NULL){ //Aloca memória e checa se foi alocada

é completamente desnecessário, e apenas polui o código cada vez mais, porém poderíamos ter um comentário assim:

/* Vamos alocar a memória necessária para
* termos uma variável com capacidade de
* armazenamento suficiente para podermos
* trabalhar com o que temos em stdin
* e executar de forma rápida nosso algoritmo de
* criptografia. */
if((buff=(char*)malloc(sizeof(char)*100))==NULL){

Dessa forma explicamos que estamos alocando dinamicamente e para que serve essa alocação, assim como seu espaço. O estilo de comentário nos leva a outro assunto, blocos. Uma regra básica nos diz:

  • Comentários de uma linha são comentados utilizando // (ou o identificador da linguagem em questão, responsável por comentar apenas uma linha)
  • Comentários longos, ou mais complexos são comentados utilizando /* */ (ou os identificadores da linguagem em questão, responsáveis por comentar múltiplas linhas)

Alguns programadores, em tempo de desenvolvimento, costuma comentar tudo com o comentário de linha simples, por um motivo básico, você está desenvolvendo e, se tiver algum problema na função, no lugar de apagar a função, você pode apenas comentar com um comentário de múltiplas linhas apenas e não precisa ficar arrumando seus comentários antigos. Porém um programa feito assim que se encontra em produção irá pecar no estilo, pois a maioria das IDEs de programação consegue entender um conjunto /* */ e possibilitar uma função chamada de folding, que compacta o comentário, mostrando apenas a primeira linha, já se for um comentário de linha única, isso não é possível.

Outro grande problema dos comentários, é a língua utilizada. Não existe uma regra fixa quanto a isso, porém pode-se seguir essas duas regras

  • Se o programa for apenas de exemplo, como um tutorial, a língua utilizada deve ser a mesma que no tutorial
  • Se o programa for final, ou um programa complexo que outras pessoas podem vir a utilizar, os comentários devem ser feitos em inglês.

A escolha do inglês é feita pois todo bom programador deve pelo menos ter uma noção de inglês, que é uma língua simples, e já está sendo considerada universal.

Por favor, comentem seus códigos, muitas vezes os programadores não sabem por que você fez da forma como fez, e isso também ajuda a você mesmo a lembrar algumas coisas, quem lembra o por que fez da forma x o programa depois de 6 meses sem ver o mesmo?

About Zarnick

Programer, sysadmin, guitarrist, and Italian. That's what I am. Plain simple.
Tips