NUNCA mais comente seu código!
Aprendendo a técnica do código descritivo
Toda vez que você pega um livro ele menciona como os comentários são importantes… Isso é realmente verdade?
Existem 3 tipos de desenvolvedores. O primeiro tipo são os desenvolvedores que nunca usam comentários. O segundo tipo são os desenvolvedores que começam usando comentários, mas à medida que prosseguem com o seu desenvolvimento, em algum momento eles param. O terceiro e último tipo são desenvolvedores que sempre usam comentários.
Eu sou do tipo 1 e, muito provavelmente, você precisa continuar essa leitura para entender o porquê.
A razão pela qual eu odeio comentários é porque eles são muito difíceis de manter. Você começa a usá-los, mas em algum momento você se sente como estivesse gastando muito tempo com eles. Você está costuma gastar muito tempo? Então você é o tipo de usuário 3 (sempre comenta).
Se você mudar algo no código, você tem que mudar o comentário, para refletir a mudança recente. Você corrige uma vez, duas vezes, a terceira vez você desiste, “SÓ dessa vez”, sem o saber que você caiu para o segundo tipo (o que desiste)!
O que eu prefiro fazer, é algo que eu chamo de código descritivo, deixe-me explicar … (Eu sou do tipo 1, nunca comento nada!)
O exemplo abaixo está reduzido, levando em consideração a estrutura do Framework Laravel e a maneira que o Eloquent funciona, e claro, a Injeção de Dependência (DI). Se você não fazer uso do Framework PHP Laravel, então o exemplo abaixo pode ser um pouco mais difícil de ler.
Suponha que você tenha uma classe PHP onde você cria um produto, aplica um desconto ao produto que você acabou de criar, e notifica os usuários sobre o produto recém-criado com algum tipo de notificação.
Então, nós temos 3 etapas em nosso estudo de caso.
Criar produto
Aplicar desconto
Notificar os usuários
O que alguns desenvolvedores tendem a fazer, é colocar tudo em um único método (função) e é aí que o problema começa.
Imagine algo assim:
Falando a verdade, isso machuca meus olhos. Muito código em uma função e muitos comentários que fazem o código ilegível. A função simplesmente faz MUITA COISA!
Tudo bem, vamos refatorar ele com um pouco de código descritivo e se livrar desses comentários.
Mencionei acima que temos 3 etapas principais, o que eu gostaria de fazer, é criar uma função para cada etapa.
Na verdade, seria ainda melhor ter uma classe específica para cada uma destas 3 etapas, uma vez que todos estes passos não tem nada em comum. Mas, para manter as coisas simples e porque estamos apenas exemplificando, eu vou adicioná-los em nossa classe imaginária Product.
Agora podemos começar a usar essas funções protegidas na nossa função de criar o produto.
Mas primeiro, vamos pegar um pouco de código do método de criar e colocar dentro de sua respectiva função.
Você deve ter notado que eu deletei os comentários, a razão pela qual eu fiz isso, não é para mostrar que “Olha, eu estou certo e com o que eu fiz, os comentários são redundantes agora.”
NÃO! Comentários são redundantes por causa da técnica que usamos.
Você não precisa de mais de um comentário para descrever que o createProductvai criar um produto, ou que os notifyUsers notificar os usuários com esse método que passamos ou que a função applyDiscountvai aplicar um tipo de desconto para o produto que passamos …
Agora veja, que ficou óbvio sem comentário!
Tudo o que temos a fazer é chamar essas funções dentro de nossa função de criar e pronto.
Este é o código que eu gostaria de ver.
E os comentários? Redundantes! Nossa função de criar é agora uma verdadeira beleza!
Você sabe exatamente o que ele faz e perceba como cada método protegido faz exatamente uma coisa.
Se você tiver trabalho para entender o que essa função faz, provavelmente você está fazendo algo de errado. :)
Comentários são tão ruins assim?
Nem tanto. Há casos em que você deve usar comentários e se você não fizer isso, então eu vou atrás de você e vou te pedir gentilmente para usar comentários.
Se você escreveu um código muito difícil, então a última coisa deve deixar de fazer é comentar! Nestes casos, os comentários são necessários para entender detalhes do que aquilo faz!
Resumindo, abaixo veja a diferença e como você deveria começar a agir.
Antes
Depois
Esta é a magia de escrever um código descritivo!
Código deve ser como ler um bom livro — alguém
