Código Limpo – Parte 03

Olá, tudo bem?

Vamos falar sobre a terceira parte do tema: “Código limpo”? Os primeiros artigos você encontra a seguir: Código Limpo – Parte 01, Código Limpo – Parte 02

Eu alterei a ordem do tema Código Limpo e hoje estaremos falando sobre Comentários:

  • Comente explicando o “por que” – Seu comentário deve explicar o porquê de sua execução e não “como”. A parte do “como” deve ser explicada pelo próprio código. Acontece que ao colocar o comentário de como o método funciona o código tende ficar mau feito, com péssimos padrões. Você começa a confiar que seu comentário irá explicar como o método deve funcionar, mas na verdade, o código deve ser “auto-explicável”.
    /**
     * This method publishes the documents using a proxy connection
     * to save the files in the necessary patterns
     * There is a loop (repetition) on going while the methods does not end
     * 
     */
    public void publishDocuments(){
        // some code...
    }

    No comentário do método está escrito o que ele faz, o modo como ele executa o processo, mas isso tem que ser percebido ao ler o código. Caso seja um pacote de classes exportadas, qual a finalidade do usuário ler esse tipo de comentário? O usuário precisa apenas saber o que esse método faz e pronto. Olhe como ficaria mais claro com o comentário mais objetivo:

    /**
     * Method that publishes the files, in html, which save them 
     * Applying w3c patterns.
     * 
     */
    public void publishDocuments(){
        // some code...
    }

    O comentário ele descreve o objetivo do método, o porquê de sua existência, e não dá descrições sobre sua implementação.

  • Sem abreviaturas – Não utilize abreviações em seus comentários, eles dificultam a leitura.
    //Hold ref to cli PPV
    Account account = daoFactory().getDaoAccount.getAccount();
    //Holds the reference to the clients Pay Per View
    Account account = daoFactory().getDaoAccount.getAccount();

    Comentando sem abreviar você gasta pouco tempo a mais digitando, mas deixa o código bem mais claro para quem o ler pela primeira vez. Lembre: “você cria o código para os outros lerem, ele te define como profissional”.

  • Não documentar o óbvio – Existem códigos que não tem a necessidade de serem documentados. Ao fazer isso, a qualidade do seu código irá diminuir. E pior, fazer isso é tão fácil…
    /**
     *Methods that calculates the bill total value
     * 
     */
    public void calculateBillTotalValue(Customer customer, Bill notPaidBill){
        // Creates the closed bill date with "today" date
        Date closedBillDate = new Date();
        
        // Sets unPaidBills to zero
        int unPaidBills = 0;
    
        // Check if the bills has the payment delayed
        if (notPaidBill.isPaymentDelayed(closedBillDate)){
            // If the payment is delayed add some interest
            notPaidBill.addInterest(closedBillDate);
        }
        
        // some code...
    }

    O código acima não precisava daquele tipo de comentário, e o comentário do método apenas repete o nome do método. Quando seu código está bem claro, não é necessário comentar todas as linhas.

    /**
     * Method that calculates the total bill value that has to be paid, add interest if needed.
     * 
     */
    public void calculateBillTotalValue(Customer customer, Bill notPaidBill){
        Date closedBillDate = new Date();
        int unPaidBills = 0;
    
        if (notPaidBill.isPaymentDelayed(closedBillDate)){
            notPaidBill.addInterest(closedBillDate);
        }
        
        // some code...
    }

    Conseguimos ler o código de modo claro, sem a necessidade de comentários desnecessários. O acúmulo de comentários repetitivos deixa seu código sujo, enorme, difícil de se ler, e ainda por cima, pode irritar o leitor. Sem falar que aumenta o tempo de desenvolvimento, pois serão muitas linhas escritas e formatadas sendo que acabam por ser desnecessárias.

  • /* fim for */ ou /* fim while */ – Colocar essa anotação ao final de uma repetição é útil apenas quando se tem uma seqüência aninhada de repetições.
    while ( /*  while controller */){
        while ( /*  while controller */){
            while ( /*  while controller */){
                
            }/* end while */
        }/* end while */
    }/* end while */
    car.turnOffEngine();

    Esse tipo de comentário torna mais claro a leitura quando temos uma seqüência de repetições aninhadas, mas fica prejudicial quando temos apenas uma repetição.

    while ( /*  while controller */){
    }/* end while */
    car.turnOffEngine();

    OBS.: No caso de muitas repetições aninhadas pode-se pensar em separá-las e colocando-as em métodos separados.

  • Comentários em excesso [1] – Quando se comenta em excesso, seu código fica poluído, difícil de ler. O foco de quem lê acaba indo para os comentários, quando o real foco tinha que ser o código escrito. Quando seu código está limpo e objetivo existe uma necessidade mínima em ter que comentar todo o código, aumentando a facilidade inclusive de localizar alguns bugs que acontecem com relação a regras de negócio, pois o foco passa de ser o comentário e vai para o código.
  • Comentários em excesso [2] – Ao notar uma quantidade enorme de comentários para um método ou algum cálculo talvez seja hora de refatorar o método. Seu código deve sempre ser claro, de fácil entendimento. Não deve existir a necessidade de escrever muitas palavras para descrever sua função.
  • Informar, caso exista, conseqüências – Sempre deixe claras as conseqüências de se executar o método. Existem métodos que podem ter conseqüências que realmente venham a afetar o comportamento do sistema de um modo não esperado. Como por exemplo: irá limpar dados temporários, apagar dados do banco de dados, iniciar, a cada chamada do método, uma conexão remota que irá pesar o processamento da máquina.
  • Necessidade dos comentários – Um código bem definido pode eliminar a maioria dos comentários. Utilize comentários apenas quando necessário, e deixe que seu código fale por ele mesmo.

Espero que esse artigo possa ter agregado valor ao seu conhecimento. Dúvidas? Basta comentar que eu respondo.

Até a próxima

4 thoughts on “Código Limpo – Parte 03

  1. Uma curiosidade: atualmente trabalho com SQL desenvolvendo códigos pra ETL. Comentários também são válidos pra esse contexto mas poucas pessoas realmente fazem tal ato. O que conclui depois de ler esse bom artigo: pior do que comentar errado é não comentar. Fica a dica pra quem não possui o hábito :)

Leave a Comment