O Júlio na gaita
e a bicharada no vocal:
fazendo rock rural
Cocórico...

Como o comentário do início deste texto introduz, um comentário pode ser bobo, incrível, engraçado, ou descartável. Depende muito de onde ele vem, de como ele é feito, do tema que ele abrange e se ele está dentro de um código. Para o nosso quarto capítulo do Código limpo do Robert C. Martin (A.K.A Tio Beto) vamos tratar do elemento computacional mais importante de toda a história. Os comentários.

No primeiro parágrafo do capítulo do livro o tio manda a letra: Comentários são fracassos. Tá, mas assim? de graça? sim. Na verdade há mais de uma justificativa para essa opinião. Se você precisa de um comentário para o seu código é porque você tem que explicar algo que seu código não deixa claro, ou que você fez de uma maneira tão tosca que é necessária uma legenda explicando aquela obra de arte ao qual chamamos de gambiarra. Não é um pecado fazer uma gambiarra, mas o mesmo tempo que você leva explicando em um comentário o que aquela massa grotesca de código faz pode ser utilizado para refinar o código e deixá-lo entendível.

Além dessa justificativa, de que o comentário de um código cagado é cagado, o tio Beto nos dá mais algumas dicas de como o comentário pode mais atrapalhar do que ajudar.

O primeiro é o famoso caso do comentário redundante. Se você leu o Capitulo 2 do código limpo você aprendeu que dar nomes para as coisas te resolve 90% dos problemas no mundo de TI (tô exagerando, só resolvem 89% por aí) um comentário pode se tornar redundante se o seu atributo tem o nome coerente.

///Esta funcao imprime a lista<people> de <Person> que recebe
/// por parametro
void printListOfNames(List<Person> people){

   //percorre a lista <people> 
   for(Person person in people){
   //imprime <name>
      print(person.name);
   }
}

Agora vamos remover os comentários.

void printListOfNames(List<Person> people){
   for(Person person in people){
      print(person.name);
   }
}

Não houve mudança alguma no código, o que acontece praticamente é o desenvolvedor poupar tempo com esse tipo de comentário redundante nas suas funções.
O que pode ocorrer também é este código se transformar, vejamos, ao invés de somente imprimir o nome de pessoas, ele somar o sobrenome da pessoa ao seu primeiro nome.

///Esta funcao imprime a lista<people> de <Person> que recebe 
/// por parametro
void addLastNamesAtPeople(List<Person> people){
   //percorre a lista <people> 
   for(int i = 0; i < people.length; i++){
   //imprime <name>
     final auxPerson = people[i];
     final newPerson = getPersonWithLastName(auxPerson);
     people[i] = newPerson;
   }
}

Person getPersonWithLastName(...)
// to com preguiça, me dá um desconto, imagine essa função aí

Repare que os comentários continuaram, mas o código mudou, mas programador é um bicho preguiçoso e o botão de delete é um dos botões mais afastados no teclado. Lembrem-se sempre dessa informação quando pensarem em inserir algo. É mais fácil não inserir do que volta a apagar.

O comentário de alerta também deve ser evitado. Ele só existe por que algo de muito errado não está certo, vamos ver um exemplo.

Future<void> login({required username, required password}){
    try{
      await repo.login(username, password);
    }catch(error){
    //erro ao fazer o login
    }
}

Deu merda, mas e ai? o que você vai fazer com isso? Esse tipo de alerta sempre vem com um problema inerente, mas isso é história de outro papo nosso.

Outro tipo de erro bastante comum nos comentário é o famoso comentário de 50 linhas. Gente? vocês tão lendo esse resumo sem ter lido o livro, quem vai ler um comentário que tem mais linhas do que a função ou o arquivo? programador sofre para ler a task, imagina ler um arquivo?

Não utilizem comentários como ferramentas de desenvolvimento a longo prazo. Se você precisa comentar um código, caso ele já esteja presente no repositório, a ferramenta de versionamento serve para isso. O Github, GitLab, BitBucket ou qualquer ferramenta que você utiliza para versionar tem um controle de commit que te permite ver a versão anterior daquele arquivo, se você vir a precisar, é só retornar a uma versão anterior ou utilizar uma ferramenta do tempo dos astecas o CTRL + C CTRL + V.

O TODO existe para uma marcação temporária, não para ficar fixo no código para a geração de desenvolvedores novatos encontrar e pensar no que aquele TODO vazio significa. Se há uma necessidade de desenvolvimento que não está no escopo da tarefa, adicione ao board, converse com o seu P.O e escreva como backlog técnico. Código não é lugar de lembrete do que se deve fazer.

Esse capítulo fecha a lista de capítulos que eu acredito ser essenciais para pessoas desenvolvedoras. Claro que até agora tivemos nossos altos e baixos com o nosso querido tio Beto. Como eu já frisei várias vezes, o que o homem diz não está gravado na pedra, ele não é uma figura messiânica, é só um cara que tem uma certa relevância no mercado e muita experiência. O que nada quer dizer sobre a qualidade do que ele prega ser bom ou não.

Sobre o projeto. Esse é o último capítulo que irei disponibilizar como resumo integral de um tema só. Irei fazer mais dois textos com as duas ultimas partes, mas como é mais avançado, não irei me aprofundar tanto (talvez eu não tenha a capacidade técnica de me aprofundar em alguns tópicos, como concorrência por exemplo).

Se puder, me deixa um comentário, uma opinião, um coraçãozinho no post. Compartilha com o coleguinha que deixa seu código todo cagado com quem n quer nada se pah...