sexta-feira, 29 de setembro de 2017

Cuidado com os comentários, eles são perigosos !!!

Olá ! Meu nome é João Paulo Maida e bem-vindos ao blog Preciso Estudar Sempre.

Mamãe sempre me disse que comentários são perigoso, e você já comentou o seu código alguma vez na vida ? Já se pegou escrevendo algo do tipo “aqui verifico se é diferente de nulo para não dar erro” ou “se condição igual true é porque idade é maior de 18” ? Se sim, não se desespere pois essa prática é muito comum para quem desenvolve software, porém não é uma das melhores e afirmar isso é o que realmente assusta a maioria das pessoas.
Duas mulheres fofocando. Uma fala no ouvido da outra e causa espanto.
Figura 1 - Cuidado com comentários, eles são perigosos !!!
Mas como um simples comentariozinho seria algo tão grave assim ? Muitos podem afirmar que o que estou dizendo é non-sense ou bobagem, já que comentários são ignorados em processos de compilação. Entretanto, devemos nos lembrar que antes de estarmos escrevendo “linguagem de máquina”, estamos escrevendo texto que outros poderão ler. De que adianta para um autor escrever um livro que ele só entende, ou escrever um livro que para cada parágrafo ele precisa explicar o que realmente ele quis dizer ?

Se ele precisou explicar através de um comentário qual era sua verdadeira intenção, então ele falhou em escrever o texto pois o próprio por si só não consegue ser expressivo bastante para passar sua própria ideia. Em miúdos, podemos concluir que um código-fonte de qualquer linguagem que falhe em passar seu próprio propósito de existência para qualquer leitor é um código defeituoso.

Neste momento espero ser apedrejado até a morte !!!
A figura mostra três homens apedrejando um outro homem de bata branca, com aparência de religioso. Existe um homem atrás de todos, com bata verde que só observa. O homem apedrejado parece pedir ao seu Deus misericórdia.
Figura 2 - Eu sendo cruelmente apedrejado
Bom, se você está lendo isto é porque ainda não fui apedrejado 👌.

Então se você se encaixa no que disse acima, você produz um código defeituoso. Um software deve ser escrito de forma que outros possam lê-lo como se fosse um livro, suavemente. As intenções de todos os elementos, desde daquela minúscula variável até aquela classe mega complexa, devem estar claras ao ponto de que com uma simples passada de olhos um outro programador que nunca tenha visto aquilo possa entender ou ter uma ideia do que está sendo feito.

Como disse no início do texto, esse assunto sempre gera muita discussão, mas é uma das principais métricas quando o assunto é código limpo. Se a sua intenção é, assim como a minha, o self-improvement, ou seja, crescimento pessoal, não se ofenda com o fato de que o código que produz não ser tão bom quanto pensava. Eu já passei pelo mesmo, me surpreendi várias vezes e reaprendi coisas que eu já achava que sabia. Acredito que faz parte passar por isso, quem consegue aprender sem errar ?

O livro que abriu minha mente para a produção de um código mais limpo e expressivo foi o Clean Code, escrito por Robert C. Martin, conhecido também pelo apelido Uncle Bob. Um grande amigo me apresentou a obra e me emprestou o seu livro em português. Comecei a ler e fiquei abismado com a riqueza de detalhes que o simples nome de uma variável pode ter. Depois de um tempo abdiquei do livro emprestado por questões de mobilidade, e baixei o PDF para meu celular. Todo momento livre que eu tenho dou uma lidinha nele, nem que seja cinco minutos. Ele é aquele tipo de livro que você tem que ler várias vezes porque no fim das contas você sempre aprende algo novo.

Existe um capítulo dedicado sobre o estudo de comentários (capítulo 4), onde são abordados assuntos como consequências de um código comentado, categorização, como programar sem comentar, bons e maus comentários, entre outros. O que estamos discutindo aqui é somente uma fração do que o livro cobre. Logo, para mais detalhes dê uma lidinha neste capítulo, vale bem a pena 😊. Deixarei um link para download no fim do post.
A capa do livro traz uma imagem de uma galáxia
Figura 3 - Clean Code escrito por Robert C. Martin
Não pense que sou contra Javadocs, sou muito a favor inclusive. Mas um Javadoc é algo completamente diferente de um comentário explicativo de uma linha de código, e mesmo assim se o Javadoc ferir algumas regrinhas que o livro aborda, então ele possui problemas. Adiante veremos um exemplo de código com o que considero um comentário ruim.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
public class BadComment {
    /*valores*/
    private final int[] valores = {1,2,3};
   
    private void verificarValores(){
        //verifico se existem valores
        if(valores.length>0){
            System.out.println("Tem valores !!!");
        }
    }
   
    public static void main (String[] args){
        new BadComment().verificarValores();
    }
}

Para um tempinho e olhe bem a amostra de código acima. Me diga, para que raios uma pessoa cria um comentário (linha 2) com o mesmo nome do atributo da classe ? Pra que isso serve ? Do que adianta ? Qual vantagem traz ? Sinceramente, nunca consegui responder tais questões e já vi isso acontecer várias vezes.

Calma porque ainda vai piorar !

Um outro programador começou a trabalhar nessa classe e resolveu mudar de lugar o atributo valores mas esqueceu de levar o comentário junto. Olha só o que aconteceu.


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
public class BadComment {
    /*valores*/
    
    private void verificarValores(){
        //verifico se existem valores
        if(valores.length>0){
            System.out.println("Tem valores !!!");
        }
    }
    
    private final int[] valores = {1,2,3};
    
    public static void main (String[] args){
        new BadComment().verificarValores();
    }
}

Agora quem for trabalhar em cima dessa classe vai ficar confuso. Porque existe esse comentário na linha 2 ? O que ele está fazendo aí ? Essas são umas das perguntas que são feitas quando isso acontece. Tal fenômeno leva os programadores ao medo, pois é criado o receio de que se algo é mudado o sistema inteiro pode parar em produção. Um sistema que não pode sofrer alterações ou testes está doente.

Analise agora o comentário da linha 5 da amostra acima. Qual é a expressividade que ele nos traz ? Obviamente, ele explica o que está sendo feito e pode até ajudar em uma primeira instância. Porém, e se alguém mudar a instrução if da linha 6 de lugar ou mudar a condição ? Será que o comentário vai acompanhar a mudança ? Senão acompanhar, será que uma outra pessoa vai entender que ali havia uma verificação, ou talvez se a que existe ali condiz com o respectivo comentário ? Note que a teia de dúvidas não pára de ser tecida, está na hora de dar um basta nisso.


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
public class BadCommentConsequence {
    
    private final int[] valores = {1,2,3};
    
    private void verificarValores(){        
        if(temValores()){
            System.out.println("Tem valores !!!");
        }
    }        
    
    private boolean temValores(){
        return valores.length>0;
    }
    
    public static void main (String[] args){
        new BadCommentConsequence().verificarValores();
    }
}

Nossa classe deve ficar como mostrado acima. Antes de tudo, adeus para comentário de atributo, isso não faz o menor sentido. Um atributo ou uma variável deve mostrar o motivo de sua existência através de seu nome e não por um comentário.

O comentário da linha 5 também foi embora e a condição do if possui um método próprio com um nome bem expressivo, que mostra qual é o motivo dele estar ali. Agora sabemos que somente será impresso algo no console quando existirem valores. A consequência dessa refatoração é uma leitura muito mais limpa e simples.

Conclusão: Um código bem feito, limpo e enxuto passa muito significado. Esse é um dos fatores mais importantes no desenvolvimento de software e uma das maiores preocupações que devemos ter se nossa intenção é produzir um bom trabalho.

Não se preocupa em errar, todos erram ou erraram um dia. Saber que errou e permanecer no erro que é o verdadeiro problema. A construção de um bom código requer um ciclo de revisão contínuo, ou seja, o que você fez hoje pode ser melhorado amanhã .

O livro apresentado é uma das referências no assunto. Selo de recomendação de leitura do Maidão.

Terminamos mais um post !! 😀

Espero que você tenha gostado. Até a próxima minha boa gente ! 😘

Leia nossa postagem anterior: Ausência do blog e férias

Dúvidas !? Sugestões ?! Críticas ou elogios ?!

Deixe aí nos comentários, envie um e-mail ou uma mensagem na nossa página do Facebook.

Download no GoogleDrive: clique aqui
Download no Dropbox: clique aqui

E-mail: precisoestudarsempre@gmail.com
Facebook: https://www.facebook.com/precisoestudarsempre/
Canal Preciso Estudar Sempre: https://www.youtube.com/channel/UCUoW8dS38rXr0a5jWU57etA

Referências
Leia Mais ››

quarta-feira, 20 de setembro de 2017

Ausência do blog e férias

Olá ! Meu nome é João Paulo Maida e bem-vindos ao blog Preciso Estudar Sempre.

Você deve ter notado que eu dei uma parada nas postagens, uma sumida. Sim, eu estava de férias. Estava recarregando minhas baterias, descansando minha cabeça para voltar com potência total com novos assuntos e motivação lá nas alturas. Se você sentiu minha falta nesse período, fico feliz com sua preocupação e carinho até porque é isso que mantém nos trilhos e trabalhando.

Minhas férias foram repletas de novas descobertas, aprendi muito e me reinventei. Pensei sobre diversos pontos, um deles é a trajetória do blog. Devo confessar que senti uma pontada de vontade de engavetar o blog, dar uma parada, descansar mais. Contudo, tenho certeza de que essa seria uma péssima escolha, a qual iria me arrepender profundamente no futuro. O laço, que com muito custo consegui construir com vocês, leitores, é muito importante. Foram anos de dedicação em trazer novos assuntos e de esforço em divulgar o material aqui publicado. A consequência disso são os poucos porém valiosos comentários que tenho de pessoas reais dizendo que de fato eu ajudei elas. Isso, meus amigos, não tem preço.

Ter uma visão voltada para o futuro do blog se faz necessária nesse momento e para haver um futuro é necessário entender o passado, acredito. Um dos pilares que sustenta a idéia do blog é a vontade de se estudar qualquer assunto. Então, pense nas antigas civilizações e o quanto ainda temos que aprender com elas.

Os egípcios, por exemplo, são mestres na arte da engenharia e seu legado possui valor inestimável para a humidade. Contudo ainda existem questões não respondidas. Mais uma vez estamos diante do mesmo questionamento, é necessário entender o que aconteceu milhares de anos atrás para poder entender o presente e pensar em um futuro. Então é isso o que precisa ser feito aqui e agora.

Não quero me estender muito neste assunto até porque esse não é objetivo desta publicação e não temos tempo a perder. Esta declaração é apenas uma satisfação que acho que vocês, leitores, merecem por uma questão de consideração. Feito isso, me despeço e peço que aguardem pois novidades estão por vir.

Até a próxima minha boa gente ! 😘

Leia nossa postagem anterior: Um roteiro para o estudo da teoria dos grafos

Dúvidas !? Sugestões ?! Críticas ou elogios ?!

Deixe aí nos comentários, envie um e-mail ou uma mensagem na nossa página do Facebook.

E-mail: precisoestudarsempre@gmail.com
Leia Mais ››