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...
Top comments (9)
Conteúdo otimo, parabéns!!!
A introdução do cocoricó roubou a cena, me lembro do meu filho b.b. que ficava no meu colo uma janela com o cocorico, e eu na outra workando ... eu decorei o dvd do cocoricó!!!!
Obrigaada. O cocoricó veio de uma piada interna. Um amigo mora no sítio e sempre tem um galo cantando na call e pra piorar, o nome do cara é Julio. Sempre que a gnt precisa comentar algo, vai um cocoricó de aviso
Valeu prima, vou acompanhar muito sua série.
Ótimo post prima! Achei muito boa a citação sobre comentários de 100km kkkkkkkkk
Valeu pelo post. Certamente deixou as coisas muito mais claras do que as 20 páginas do Clean Code que tentaram explicar isso.
Tentei resumir tudo mais fácil e sem perder a essência do que realmente é importante daquelas páginas
Ótimoo artigo! Recentemente estive lendo esse capítulo dos comentários, você passou bem a visão sobre o capítulo de uma forma que ficou divertido/fácil de se ler, gostei do post! ;)
Obrigaada! Fico feliz que gostou. Eu tentei simplicar e facilitar bem o que era pra ser simples desde o ínicio.
Que post foda prima!