Tratando Exceções em uma Aplicação Web

Pessoal, boa noite. Tudo bem?

Vamos falar um pouco sobre como capturar exceções em uma aplicação web? Para aprender como criar uma aplicação web, visite esse tutorial: Criando um WebServer. Vamos usar esse projeto adicionando o tratamento de erros.

Situações inesperadas vão sempre acontecer, e pior ainda é quando problemas inesperados são exibidos ao cliente através mensagens que faz com que ele passe a ter certa desconfiança da funcionalidade. Esteja certo de que todo problema que ocorre a partir de então será “causado” pelo seu sistema na visão do usuário (mesmo sendo a internet que tenha caído).

OBS.: Nos artigos que costumo escrever não peço por tecnologia específica, mas por enquanto terei que fazer. Por favor, não usem o Intert Explorer (ou o browser do eclipse)! Ao final do artigo irei explicar o porquê desse pedido, pois esse pequeno detalhe me custou quase 120 minutos para descobrir o motivo do código não funcionar no IE (em pleno final de semana).

No código do projeto Servlet (Criando um WebServer) caso o usuário não digite um valor válido, utilizamos o seguinte código para tratar essa situação:

try {
    // I know this is ugly, but in a future we can do some refactor and apply some OO and Design principles
    value1 = Integer.parseInt((String) req.getParameter("valor1"));
} catch (NumberFormatException e) {
    // Catching this execption in case some invalid value was sent
    value1 = 0;
    warning = "We got some bad value(like blank or non numerics values, we set 0 instead";
}

Nesse exemplo quando acontece o erro um valor padrão para o usuário é passado, mas e quando essa situação não é possível? Existem situações em que quando uma exceção acontece temos que parar todo o processo e informar ao usuário que algo está errado. Existem também erros causados e que não são capturadas por nossos servlets, um exemplo disso é quando o usuário tenta acessar um recurso que não existe e um erro HTTP 404 é exibido em sua tela. Vamos tratar o erro do acesso indevido (404) e depois o erro nos dados (valor inválido digitado).

Vamos criar primeiro uma jsp para tratar nossos erros que ficará assim (crie a jsp dentro da pasta WebContent com o nome de “error.jsp”):

<%@ page isErrorPage="true" language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        <title>Erro</title>;
    </head>
    <body>
        Ops, something happend! <br/>
        Error code: ${pageContext.errorData.statusCode}
    </body>
</html>

A atribuição isErrorPage permite que tenhamos acesso ao objeto do exception. O objeto errorData é criado pelo container e colocado no pageContext de modo automático. Basta configurar o “web.xml” para que o servidor possa encaminhar o erro obtido até a jsp.

O nosso arquivo web.xml terá as seguintes linhas a mais:

<error-page>
    <error-code>404</error-code>
    <location>/error.jsp</location>
</error-page>

Com a tag configuramos o código do erro e qual o seu destino. Quando nosso usuário digitar um endereço inválido, ele será direcionado para nossa JSP de erro.

Para testar, inicie o container e depois basta digitar um endereço inválido apontando para dentro da nossa aplicação, como por exemplo:

http://localhost:8080/Servlet/ASD

Não existe a action ASD mapeada em nosso arquivo web.xml com isso ao invés de ser exibida a mensagem HTTP 404, será exibida nossa jsp responsável por tratar os erros. Veja como essa simples configuração conseguiu evitar uma mensagem que o usuário não iria entender nada.

Outro modo de tratar exceções pode ser direcionar o erro gerado para um servlet onde poderemos trata-los. O nosso código gera uma exceção quando tentamos realizar a soma sem digitar valor algum e na primeira versão desse programa, colocávamos um valor padrão para a variável, mas agora, iremos exibir uma página de erro onde o usuário verá que é necessária a entrada dos dados numéricos.

try {
    valor1 = Integer.parseInt((String) req.getParameter("valor1"));
} catch (NumberFormatException e) {
    throw new NumberFormatException("No numbers were typed");
}

Veja como nosso código ficou, não estamos tratando mais a exceção, mas estamos informando para o container que algo aconteceu e é para que ele trate essa exceção.

Mas essa alteração, ainda não foi mapeada no arquivo “web.xml”.

<servlet>
    <servlet-name>errorServlet</servlet-name>
    <servlet-class>com.ErrorController</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>errorServlet</servlet-name>
    <url-pattern>/errorServlet</url-pattern>
</servlet-mapping>
<error-page>
    <exception-type>java.lang.NumberFormatException</exception-type>
    <location>/errorServlet</location>
</error-page>

Mapeamos o servlet que irá tratar o erro, e também informamos que todo erro do tipo NumberFormatException será tratado pelo nosso servlet. Poderíamos trambém declarar que ele irá capturar uma java.lang.Exception que toda e qualquer exceção seria tratada por nosso servlet.

Precisamos agora criar nosso servlet para tratar as exceções.

package com;

import java.io.IOException;

import javax.servlet.RequestDispatcher;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * Servlet implementation class ServletError
 */
public class ErrorController extends HttpServlet {
    /**
     * 
     */
    private static final long serialVersionUID = 1L;

    public void doPost(HttpServletRequest req, HttpServletResponse res)    throws ServletException, IOException{
        Throwable throwable = (Throwable) req.getAttribute("javax.servlet.error.exception");
        Integer statusCode = (Integer) req.getAttribute("javax.servlet.error.status_code");

        req.setAttribute("errorType", throwable);
        req.setAttribute("statusCode", statusCode);

        RequestDispatcher requestDispatcher = req.getRequestDispatcher("/error.jsp");
        requestDispatcher.forward(req, res);
    }

    public void doGet(HttpServletRequest req, HttpServletResponse res)    throws ServletException, IOException{
        doPost(req, res);
    }   
}

Vamos realizar uma pequena alteração em nossa JSP de erro como bonus? A partir de agora ela irá exibir também o tipo do erro:

<%@ page isErrorPage="true" language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        <title>Erro</title>
    </head>
    <body>
        Ops, something happend! <br/>
        Error code: ${statusCode} <br/>
        The error type is: ${errorType.message}
        <br/>
    </body>
</html>

Foi alterado também o código do erro para ler o valor colocado no request em nossa Servlet, e na página estamos exibindo o conteúdo do objeto que foi criado de modo automático pelo container.

Inicie o Tomcat e mande realizar a soma sem ter número algum e o nosso container irá entender que houve uma exceção e irá redirecionar para o servlet que irá tratar o erro e finalizar a requisição na página de erro.
Utilizando um servlet para tratar de nossos erros podemos realizar diversas outras funções que não seria possível fazer apenas direcionando diretamente para a JSP. Podemos por exemplo, gravar no log da aplicação, enviar email para os responsáveis, etc.

Vou falar um pouco agora, do porque pedi a você para não usar o IE (Internet Explorer). Quando uma exceção acontece, o container altera o valor de uma variável chamada SC_INTERNAL_SERVER_ERROR, com isso o IE nota que esse cara teve seu valor alterado e passa a tratá-lo de um modo próprio que no caso, ignora o tratamento que foi dado no arquivo “web.xml”. Tente executar nossa aplicação agora pelo IE e note como ele acaba por tratar a exceção.

A primeira solução seria alterar uma configuração dentro do próprio IE. Ela fica em:

Opções da Internet > Avançadas > "Mostrar mensagens de erro http amigáveis"
Ou IE em inglês:
Internet Options > Advanced > "Show Friendly HTTP Error Messages"

Desmarque a opção, salve suas alterações, feche o IE e abra novamente e faça o mesmo teste. Perceba que agora ele já exibe a mensagem que desejávamos. Mas, como iríamos pedir que todo usuário de nosso sistema fizesse essa alteração? Imagine que um usuário iria pela primeira vez em nosso site, mas ele acabou por digitar o endereço errado, como ele iria ficar sabendo dessa opção?

A segunda solução, é alterar o status do objeto “response”. Quando alteramos esse status o IE passa a aceitar que não houve nenhum erro e nossa página será exibida normalmente.

req.setAttribute("statusCode", statusCode);

res.setStatus(HttpServletResponse.SC_OK); 
// We have to remove the exception from the request. If we do not remove the IE9 will not display out error page.
// IE9 will think that some error created a crash inside our application if we do not remove the exception from the request.
req.setAttribute("javax.servlet.error.exception", null);
req.setAttribute("javax.servlet.error.status_code", null);

RequestDispatcher requestDispatcher = req.getRequestDispatcher("/error.jsp");

Realmente, essa parte do IE me tomou boa parte do fim de semana e inclusive durante a semana conversei muito com meu chefe sobre isso e só depois de mais pesquisa que encontrei esse assunto de modo mais detalhado.

Espero ter ajudado. Qualquer dúvida basta falar.

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

Clean Code – Part 03

Hello, how are you?
Let’s talk about Clean Code? The first’s articles you will find here: Clean Code – Part 01, Clean Code – Part 02
I have changed the Clean Code subject order and today we will be talking about Comments:

  • Comment telling the “why” – Your comment must tell the “why” of the methods being invoked and not “how” it works. The “how” part must be clear when you read the code. When we write how the code works as comments your code will tend to have a bad design, and it will have no patterns. You might start to trust that your comment will explain how the method works instead the code itself. Remember that your code should be “self-explaining”.
    /**
     * 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...
    }

    The methods comment is written what it does and the way it executes the process, but this must but noticed when we read the code, not when we read the comment. If we have methods that were inside an exported package, which purpose would have to the user reading that kind of comment? The user must only know what this method does. Let’s see how a comment can be clearer:

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

    The comment must describe methods purpose, and the why of its existence, and do not give information about its implementation.

  • Do not abbreviate – It is not a good idea to shorten the words in the comments, shortened words make your comments difficult to read and to understand.
    //Hold ref to cli PPV
    Account account = daoFactory().getDaoAccount.getAccount();
    //Holds the reference to the clients Pay Per View
    Account account = daoFactory().getDaoAccount.getAccount();

    Writing the comment without abbreviating it you will expend just a little more time but it will make easier for anyone to read it at the first time. Recall: “You create your code so other people might read it; it defines you as a professional”.

  • Do not comment the obvious – There is some kind of codes that does not need any comment and when you do it, you decrease the quality of your code. And it’s so easy to do this…
    /**
     *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...
    }

    The code above didn’t need of that kind of comment, and the method comment just repeats the methods name. When your code is clear, you won’t need to comment every line.

    /**
     * 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...
    }

    We are able to read the code above in a clear way, without needing those comments. If you have to much unnecessary comments your code gets dirty, huge, hard to read, and worst, can turn the people that read it angry.

  • /* end for */ or /* end while */ – Putting this kind of comment is useful only when you got nested repetitions(loops).
    while ( /*  while controller */){
        while ( /*  while controller */){
            while ( /*  while controller */){
                
            }/* end while */
        }/* end while */
    }/* end while */
    car.turnOffEngine();
  • This kind of comment makes the reading clearer when we got a sequence of nested repetitions (loops), but it turns harmful when we have just one repetition(loops):

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

    PS.: If you have a lot of nested repetitions(loops) maybe it’s time to split them in separated methods.

  • Comments overplus [1] – When you put too many comments in your code, you get a dirt code, hard to read. The focus of someone that reads it will go to the comment instead the code, which should be the one receiving the focus. When you have a clean code there is almost no needing of putting comments, and even better, it raises tracking chances when are looking for some business bug code, because, your focus will go to the code instead of going to the comment.
  • Comments overplus [2] – If your see a lot of comments in one of your methods maybe it is time to do some refactor. Your code must always be clear, of easy understanding. Don’t use too much words to describe your methods, if you do, there is something wrong.
  • Warn about consequences – Always let the user know if your method has any consequence after been invoked. There are some methods that may affect the software behavior in an unexpected way. As sample: clear temporary files, erase database data and to start a process of remote connection that would overflow the server processing.
  • Required Comments – A clear code it’s able to eliminate most of the comments. Use comments just when it’s really needed, let your code speak for itself.

I hope this post might have aggregate some value to your knowledge. Any doubt? Just comment that I will answer.
See you soon.

TDD – First Steps

What is TDD? Where do we start? How do we do a test?

TDD is a methodology to validate classes/methods/attributes that will be created. By example, if it were asked to create a method that searches the data from a house. With TDD, it is possible to validate all situations that the developer might imagine, like: house without number, null as a method return, owner has died and etc.

Where do we start? We need to configure do JUnit so it will make our vision about TDD clearer. I’m sorry if you already know how to do this, it will be fast (we got to help the rookie!).
I will be using the Eclipse as IDE, but TDD should (and must) be applied to all kind of IDEs. Just in case you don’t use JUnit as you test framework, the concept that you will see in here it is applicable to TDD in every framework.

PS.: The little details such to create packages/classes or to open an Eclipse’s view you may find here: Creating a WebServer.

I’ve created a Project named TDD. Then, using “Package Explorer” view, add JUnit library:
Config 01
Config 02
Config 03

We are going to write a test to this user case: Your project will have a class named User that will store all information about each person logon/logoff in your software. As requirement, this class will have a method that will block the user access to the software. Let’s create a package name “test.com” and a class named TestUser inside this package.

package test.com;

public class TestUser {
}

The TDD ideology is that we should start a test by its end. (WHAT?!) In the software companies today is common to start writing a code from where it should start, but with TDD we start it from its ending. Why? By coding using TDD, we got an idea that will lead us to where we supose to be going, we avoid the creation of unnecessary parameters, the created methods are more cohesive and then it goes…
When we write tests cases we must have this sequence in mind: “Red, Green and Refactor”. What does this mean? When we write tests cases using JUnit we have a red bar (that we will see very soon) showing red status when our tests fail and green when all tests are executed with success.

To get the expected result we might use methods that will guarantee that result for us. We will be using assertEquals(desired value, returned value). In our user case, what do we want? Always that the User got a denied access our method should return true. Let’s do some code?

package test.com;
import static org.junit.Assert.*;
import org.junit.Test;

public class TestUser {
    @Test
    public void isUserWithDeniedAccess(){
        assertEquals(true, user.accessDenied);
    }
}

Let’s talk about this code. Observe that we got the annotation “@Test” and when we run the JUnit framework, it will locate all methods with that annotation and will invoke the test validation. We can see the assertEquals that we imported from the JUnit doing an “import static”. Notice that I’m already “trying to access” an object that does not exists in the method or not in the project either. Do you remember when I said that we should start from its ending? Our ending (goal, target) is that the User gets really no access to the software. Even if the class/attribute/methods it is not in the software code yet, as first steps, we will use it regularly. Writing the code by its ending enable us to start to think on the classes name, attributes and etc.

Even if the code does not compile, we are on the way… Small steps… Always small steps.

And to finish our test, the code will be like:

@Test
public void isUserWithDeniedAccess(){
        User user = new User();
        assertEquals(true, user.accessDenied);
}

Observe that the User class was “instantiated” even when it does not exist in our TDD test software. Now we have a test case that we can’t compile.

Are you remembering TDD steps: “Red, Green and Refactor”? To archive the red bar we need first to remove all compile errors. Let’s create our class User inside a package named “com” and create the needed attribute.

package com;
public class User {
    public boolean accessDenied;
}

To finish, create the import statement in our test class (TestUser):

import com.User;

We are ready to get the read bar. To run the test using the JUnit just right click on the test class and go to “Run as > JUnit Test”.
Running JUnit

The red bar gives us the message that we are ready to work in our method, so the method will return the desired value. We start with an error to be sure that, when we get the green bar, our method is really working as we wished. In our situation, we are doing a simple test, but if we were doing a complex method, would give us the assurance that that we got our goal complete. Using a test unit, allow us to not need to build the application every time to test our recently created method. We just need to execute the tests and check the result of our coding.

Our next step will be to get the green bar. Usually at this part of the process we write the code to our method. This simple use case that we are doing does not need a method to be tested yet; we just need to change the attribute value. Our test is the one that does the change at the classes attributes, stimulating it to get the test value that we want. That’s why we are not changing our User class, but we are using our test method to stimulate it by changing its value so the User class might behave as we want. TDD works with small steps if you already have a good knowledge you might create the necessaries methods instead taking this small steps. But, it is a good idea to access directly the attributes, by small steps, because we are already testing them. And late, we will do some refactoring to encapsulate those attributes.

@Test
public void isUserWithDeniedAccess(){
        User user = new User();
        user.accessDenied = true;
        assertEquals(true, user.accessDenied);
}

Run JUnit again and you will get a green bar.

And what do we have? The uglier working code ever and there is nothing if we start to looking for OO/Design patterns. What should we do? The methods/attributes refactoring should stay to the end. Let’s add these refactoring at our “TO-DO” list, doing this list will help us to do not forget about something.

Using this approach we got a better code view from where we could change it and “upgrade it”. It’s just get better, we are sure that our new code it is working as we desired. But we need to change our code to have OO patterns before we give the task as completed. We will create a method that will check if the user got his access denied, we need to protect our attribute.

// TestUser.java
package test.com;

import static org.junit.Assert.assertEquals;
import org.junit.Test;
import com.User;

public class TestUser {
    @Test
    public void isUserReallyBlocked(){
        User user = new User();
        user.accessDenied = true;
        assertEquals(true, user.hasAccesDenied());
    }
}

//User.java
package com;

public class User {
    public boolean accessDenied;

    public boolean hasAccesDenied() {
        return accessDenied;
    }
}

We did not change the attribute access level yet because we still have one more step. Let’s create a “way” that our class change its attribute and protect it from direct access. We will use the concept Tell, don’t ask. Write the code using this “pattern” we will have a clean and bulletproof code and our task will be complete. Our final code would be:

package test.com;

import static org.junit.Assert.assertEquals;
import org.junit.Test;
import com.User;

public class TestUser {
    @Test
    public void isUserReallyBlocked(){
        User user = new User();
        user.denyAcces();
        assertEquals(true, user.hasAccesDenied());
    }
}

package com;

public class User {
    private boolean accessDenied;

    public boolean hasAccesDenied() {
        return accessDenied;
    }

    public void denyAcces() {
        accessDenied = true;
    }
}

Observe our code and notice that our User class has a clear code, straight and without unnecessary methods. Starting the code by the test allow us to focus more on the behavior. Just run the test again to see the final green bar.

I hope this post might help you on your first steps. Soon, I will post here some good TDD practices so we can get our test case even better. Today post was more to tell about the tool, at next post we will be seeing about TDD concepts.

Good night.

TDD – Primeiros passos

O que é TDD? Por onde começar um Teste? Como se faz um Teste?

TDD é uma metodologia de validação das classes/métodos/atributos que serão criados. Por exemplo, foi solicitado criar um método que busque os dados de uma casa. Com o TDD, é possível validar todas as situações que o desenvolvedor possa imaginar, como: casa sem número, valor retornado null, dono se mudou, etc.

Por onde começar? Vamos configurar o JUnit para ficar mais clara nossa visão? Desculpe se você já sabe fazer isso, é coisa rápida (temos que ajudar quem está começando!).
Irei usar o Eclipse como IDE, mas na verdade o TDD pode (e deve) ser aplicado em qualquer IDE. Caso você use outra ferramenta de teste que não seja o JUnit, o conceito que será passado aqui é aplicável a qualquer ferramenta de teste.

OBS.: Esses pequenos passos de como criar classes/pacotes ou abrir uma view do Eclipse você pode achar em outro post aqui no blog: Criando um WebServer

Após criar um novo “Java Project” que chamarei de TDD, utilizando a View “Package Explorer”, adicione a biblioteca do JUnit:
Configurando 01
Configurando 02
Configurando 03

Vamos trabalhar em cima do seguinte caso de uso: Seu sistema terá uma classe User que manterá as informações de cada pessoa que faz o login no sistema. E como requisito, essa classe terá um método para bloquear o acesso de um usuário ao sistema.
Vamos criar um pacote chamado “test.com” e uma classe chamada TestUser dentro deste pacote.

package test.com;

public class TestUser {
}

A ideologia base do TDD é começar o teste pelo resultado esperado. (HEIN?!) No mercado o costume sempre foi começar a codificar pelo começo, mas no TDD nós começamos pelo fim. Por quê? Fazendo assim temos uma idéia para onde vamos, o que vamos precisar para chegar até lá, evitamos criação de parâmetros desnecessários, os métodos ficam mais objetivos e assim vai.

Ao escrever métodos temos que ter em mente a seguinte seqüência: “Vermelho, Verde, Refatorar”. O que seria isso? Quando escrevemos testes utilizando JUnit temos a barra (que em breve veremos) mostrando status vermelho para quando o teste falha, e verde para quando tudo é executado com sucesso.

Para garantir um resultado experado, existem métodos que fazem essa conferência. Vamos utilizar o assertEquals(valor desejado, valor retornado). Em nosso caso de uso, o que queremos? Sempre que o usuário estiver bloqueado o método terá que retornar verdade. Vamos escrever esse código?

package test.com;
import static org.junit.Assert.*;
import org.junit.Test;

public class TestUser {
    @Test
    public void isUserWithDeniedAccess(){
        assertEquals(true, user.accessDenied);
    }
}

Alguns detalhes sobre o código. Note que temos um annotation “@Test” e ao executarmos o framework do JUnit ele irá localizar os métodos que tiverem esse annotation, e irá executar a validação do teste. Estamos utilizando o método assertEquals que é importado do próprio JUnit utilizando o “import static”.

Perceba também que já estou “tentando” acessar um objeto que não existe tanto no método, tão pouco no projeto. Está lembrado de quando falei que começamos do fim? O nosso fim (alvo, meta) é que o usuário no final das contas esteja realmente bloqueado. Mesmo que não exista classe ou seus atributos ainda, iremos normalmente, como passo inicial, utilizá-lo em nosso código. Fazendo assim, já estamos pensando no nome da classe, dos atributos. Mesmo que não compile, estamos no caminho. Pequenos passos… Sempre pequenos passos…
Finalizando nosso teste, nosso código ficará assim:

@Test
public void isUserWithDeniedAccess(){
        User user = new User();
        assertEquals(true, user.accessDenied);
}

Note que foi “instanciada” a classe User mesmo sem ela existir no projeto. Agora temos um projeto em que o teste não é compilável.
Lembram-se dos passos do TDD? Vermelho, Verde e Refatorar? Temos que conseguir uma barra vermelha retirando os erros de compilação. Vamos criar nossa classe User (em um pacote chamado “com”) e adicionar o atributo necessário.

package com;
public class User {
    public boolean accessDenied;
}

Agora basta fazer o import na classe de teste (TestUser):

import com.User;

E já estamos prontos para conseguir nossa barra vermelha. Para rodar o teste pelo JUnit basta clicar com botão direito em cima da nossa classe de teste ir em “Run as > JUnit Test”.
Executando o JUnit
A barra vermelha nos indica que agora estamos prontos para trabalhar o nosso método para que ele possa retornar o valor desejado. Começamos pelo erro para saber que, ao conseguir o verde, nosso teste realmente esta trabalhando como desejamos. Nesse caso estamos a fazer um exemplo bem direto, mas se estivéssemos fazendo um método complexo, começar pelo erro faria com que tivéssemos a certeza de que atingimos nosso objetivo. Com isso, não precisamos executar toda a aplicação para fazer o teste da funcionalidade, basta rodar os testes e pronto, já podemos ver rapidamente o resultado da nossa alteração.

Agora vamos desenvolver nosso código para que nossa barra possa ficar verde? Nessa hora, geralmente, alteramos o método que acabamos de criar para retornar o valor desejado. Como nosso exemplo é simples, basta trabalhar com o valor do atributo para consigamos o valor desejado. O nosso teste é quem tem quem deve estimular a classe nas situações desejadas, por isso não estamos alterando em nada a classe User para que nosso teste execute. TDD trabalha com pequenos passos, caso você já esteja com um bom nível em TDD já seria possível criar os métodos de uma só vez. Por isso estamos acessando diretamente os atributos, mas de acordo com algumas literaturas de TDD é uma boa prática acessar os atributos pois você já estaria validando os mesmos em sua fase de teste, e depois, com a refatoração seriam criados os métodos para proteger os atributos

@Test
public void isUserWithDeniedAccess(){
        User user = new User();
        user.accessDenied = true;
        assertEquals(true, user.accessDenied);
}

E agora basta executar o JUnit o código que teremos a barra verde.

Note que nosso código está feio, e não está aplicando nenhum padrão OO. O que fazer? Esse ato de refatorar sempre fica para o final, então vamos adicionar ao final da nossa lista de tarefas onde iremos refatorar. Assim não iremos deixar nada para trás.

Usando essa abordagem de código temos uma visão melhor do código, de onde poderíamos alterá-lo ou melhorá-lo. E melhor, temos a certeza de que nosso código já está fazendo o que nós queríamos. Mas precisamos aplicar conceitos OO antes de dar a tarefa como concluída. Vamos primeiro criar um método para verificar se o usuário tem seu acesso negado ao invés de acessar o atributo direto.

// TestUser.java
package test.com;

import static org.junit.Assert.assertEquals;
import org.junit.Test;
import com.User;

public class TestUser {
    @Test
    public void isUserReallyBlocked(){
        User user = new User();
        user.accessDenied = true;
        assertEquals(true, user.hasAccesDenied());
    }
}

//User.java
package com;

public class User {
    public boolean accessDenied;

    public boolean hasAccesDenied() {
        return accessDenied;
    }
}

Não alteramos o acesso ao atributo ainda pois temos mais um passo pela frente. Vamos criar um meio para que a classe altere o atributo e proteja o atributo de um acesso direto. Para isso, vamos usar o conceito Diga, não pergunte. Fazendo assim, de um modo eficiente iremos terminar nosso caso de teste e nossa tarefa. Nosso código final seria:

package test.com;

import static org.junit.Assert.assertEquals;
import org.junit.Test;
import com.User;

public class TestUser {
    @Test
    public void isUserReallyBlocked(){
        User user = new User();
        user.denyAcces();
        assertEquals(true, user.hasAccesDenied());
    }
}

package com;

public class User {
    private boolean accessDenied;

    public boolean hasAccesDenied() {
        return accessDenied;
    }

    public void denyAcces() {
        accessDenied = true;
    }
}

Note como o código da classe User ficou claro, objetivo, sem métodos desnecessários. Começando pelo teste nosso foco é maior no comportamento. Basta agora compilar o teste utilizando o JUnit e ver que concluímos tudo com sucesso.

Pessoal, esperem que ajude esse post para os primeiros passos. Em breve irei colocar aqui, boas práticas de TDD para que possamos aprimorar ainda mais o nosso desenvolvimento. O post de hoje foi apenas uma introdução mais a ferramenta em si, no próximo post sobre TDD iremos falar mais sobre conceitos e abordagens do TDD.

Boa noite a todos.

Clean Code – Part 02

>Good night everyone, everything ok?

Let’s continue with the subject of keeping our code clean? The first part you can find in here: Clean Code – Part 01

Today we will be talking about scoped variables and attributes.
PS.: Every time I write attributes, I will be referring to both cases, OK? To scoped variables (methods parameters, definitions of variables inside of loops), and to classes attributes. By doing this I will not be repeating attributes/scoped variables all the time. It will make the text smaller and easier to read.

  • Use camelCase at attributes names – this is a basic tip and you will see it around every time. Makes the reading easier and it is adopted by a lot of other development languages. Some samples would be:
        String disapprovedStudent;
        double totalDivide;
        boolean isManager;

    An advantage is that it’s easier to read in camelCase then:

        List player_own_goals;
        List playerOwnGoals;

    A disadvantage would be for long attributes names:

    Map allYellowHousesFromTheBlock;

    That means, use it but don’t abuse.

  • List name on plural – why put a name like: “listPerson” if you just name it as “people” it will give the same idea? There is a huge difference between person and people by the meaning of those words. Keep this concept in mind and you shall see how legible your code will be. Lets see a sample of how a “foreach” would be:
        List houses = new ArrayList();
        // adds the houses from the block at the list 
        for (House house: houses) {
            this.ringBell(house);
            this.runForYouLife();
        }

    Notice that when you read the name “homes” from the list it is clear that we are talking about a group of “home”. When more often this naming “pattern” be applied to your system, clearer will be to those that read it the attribute meaning and how it is used at the method.

  • We shall name the attributes with real names and ye spoke ones, names that provide a “self-explanation”. Think in case you find this kind of attributes naming:
    public class Car{
        //... some code
        boolean caCra;
        //... some code
    }

    What that attribute suppose to mean? What it would be its purpose? How do you say that? Imagine you calling your coworker, and when you try to explain what you are doing, he asks you: “Ok, but which attribute are you talking about?”! How you would you say that?
    Having an attribute with a name straight, objective and “ye spoke” you already can imagine what it means, and when you refer about it with someone, it would be easier to be spoken and the one that is listening you, just by hear it, it might be able to remember of that code. Oh yea, that attribute name how would be if named right?

    public class Car{
        //... some code
        boolean isCarCrashed;
        //... some code
    }
  • If you see the code below, be careful. It might give you a lot of misunderstanding:
        int value1, value2, value3;
        // ou 
        String name1, name2, name3;

    What could possibly mean the one, two or three? Notice that at any moment the attribute let us know where it would be used or in which way it will be used. The code gets harder to understand. In case you got some bad luck getting a nested if/else/while with those kinds of attributes, go get a coffee because you are going to have a very long afternoon… Imagine this situation:

        String str1, str2, str3, str4;
        //... some code
        str4 = str3.substring(4,8) + str1.concat(str2);

    Now, imagine if the code had been written like this:

        String userLogin, userPassword, lastLoginDate, userAccessKey;
        //... some code
        userAccessKey = lastLoginDate.replaceAll("/", "-") + userLogin.concat("-" + userPassword);

    We are able to understand what this code is doing just by the attributes name. By doing this inside of a method with a good naming… Make a perfect combination that will make every developer, which reads your code, happy. I have seen cases that semantically (it was an OO study) which it would not have another possibility instead putting numbers at the end like 1 and 2. If you have in mind the same concept and perception, that the project would not loose its cohesion and its definition if the attributes receive the numbers in the end (1 and 2) go ahead and implement it.

  • Attributes names must make sense to the context that the attributes are being used. Always when you read an attribute name you must understand it in that code, for that specific context:
        //... some code
        int total = 0;
        for (Trade tradedBall : tratedBalls) {
            total += tradedBall.getTotalTratedItens();
        }
        for (Trade tratedHelmet : tratedHelmets) {
            total += tratedHelmet.getTotalTratedItens();
        }
        StockFacade stockFacade = FacadeFactory.getStockFacade();
        stockFacade.updateAmountTratedItens(total);
        //... some code in the same method
        //... 
        //... 15 lines after
        double totalSpent = financialFacade.calculateSpentValue(spentValuesWithEmployees + (valuePerIten * total));
        return totalSpent;

    What is that “total” that came from nowhere at the final sum? Where does its value come from? Which role it has on that method? Now, imagine if instead of “total” its name was “totalTradedItens”. Read that code again changing the “total” name for the suggested name.
    This is the difference of always give a name that has the same value at the context where it is used.

  • Do not specify the attributes type in the front of its name. It is very usual you find “intAge”, “strName”, and “dtBirth”. You might ask: “What’s wrong with it?” Remember that one of the good practices is that the attribute name should “self-explain”? Put the attribute type in front of the name has some advantages:
    • Stimulate some bad attribute naming: it is easier think in put “dtBirth” then “birthDate”. And the idea of “sex-explain” names would start to fail. Others weird names could appear like: dtBir, dtNatDe (naturalDeathDate).
    • Type abbreviations at attributes names: it would not take long to see names like: “strName”, “stName” or “nmName” (if the attribute name was just “name” it would be ok). So far nothing extravagant, but imagine if your software has a javascript and then you start to see: “cbDtSt” or “txtNmFi”. What would be your reaction? Would you know how to explain each one? Believe in me, I’m not overreacting, I’ve seen attributes with that name.
  • Have you ever thought about short attribute names and easy to type? Suppose that in your software you got an attribute named “allAliensFromTheEntireUniverse”. Now think if you have to type that attribute name every time… Would not be easier if was just “aliens”? It is easier and we could understand that it is a list. Don’t you have times that you are doing that exciting code and when you have to type the giant attribute you think: “Come on, should I have to type it again?”? With IDE’s “self-complete” it is easier to type those attributes name, but imagine someone having to choose between 5 names every time instead just typing it if a small attribute name was. Remember, an attribute name should not back away people.
  • Space between your attributes – A code that has a lot of calculations and methods calls with out spaced attributes, it is a headache! Let’s see a sample:
    total=salesPerDay(today)-(COMMITTEE_PERCENTAGE*vendors+totalSoldItens);

    A code it’s cleaner when it has space between its attributes:

    total = salesPerDay(today) - (COMMITTEE_PERCENTAGE * vendors + totalSoldItens);
  •  Avoid sending null attributes: sending null attributes it’s the root of all nullPointers! Just imagine if you are invoking a method that you never use before, but they told you: “Go ahead, put this invoking at your method and send it to the client. You can trust because this method it’s bulletproof!” But what they never told you is that you could not send a null value. When this happen (null pointer) the trust from your client to your software would be shaken.

Well folks, I hope this article might help you.

This subject will be continuated.

Código Limpo – Parte 02

Boa noite pessoal, tudo bem?
Vamos continuar com o assunto de como manter um código limpo? A primeira parte do assunto, você encontra aqui: Código Limpo – Parte 01.

Falemos um pouco sobre variáveis de escopo e atributos.

OBS.: Toda vez que eu escrever atributos eu estarei me referindo aos dois casos, ok? Tanto como variáveis de escopo (parametros de métodos, definições de variáveis dentro de loops), tanto quanto atributos de classe. Apenas para não ter que repetir atributo/variável toda hora aumentando o texto.

    • Usar camelCase no nome do atributo – essa dica é uma dica básica e bastante encontrada por aí. Facilita a leitura e é utilizado em convenções de várias linguagens de programação. Alguns exemplos seriam:
          String disapprovedStudent;
          double totalDivide;
          boolean isManager;

      Uma vantagem é que é mais fácil ler na forma camelCase do que:

          List player_own_goals;
          List playerOwnGoals;

      Uma desvantagem seria em um nome grande:

      Map allYellowHousesFromTheBlock;

      Ou seja, utilize e não abuse. ;)

    • Nome de lista no plural – para que colocar nome “listaPessoa” se colocar “pessoas” já dá o mesmo sentido? E existe uma diferença enorme entre pessoa e pessoasanalisando o conceito da palavra. Mantenha esse conceito em mente e verás como seu código ficará legível. Veja só o “foreach” como ficaria:
          List houses = new ArrayList();
          // adds the houses from the block at the list
          for (House house: houses) {
              this.ringBell(house);
              this.runForYouLife();
          }

      Perceba que ao ler o nome da lista “casas” fica claro que estamos falando de um conjunto de “casa”. Quanto mais frequente esse tipo de nomeclatura for utilizada em seu sistema, mais claro ficará para quem estiver lendo, o que o atributo significa e o seu valor no método.

    • Devemos dar nomes reais que sejam fáceis de falar, nomes que se “auto-expliquem”. Imagine só, caso você visse a seguinte declaração:
      public class Car{
          //... some code
          boolean caCra;
          //... some code
      }

      O que ela deve significar? Qual seria sua utilidade? Como se fala? Imagine você chamando seu colega de trabalho, e ao tentar explicar o que estás a fazer, ele pergunta: “Ta, mas você está falando de qual atributo?”! Como você falaria?
      Sendo o nome direto, objetivo e “falável” você já pode imaginar o que significa, e ao comentar o código com alguém, seria mais fácil de ser dito e a pessoa que o ouvir poderia se lembrar dessa parte do código facilmente. Ah sim, qual seria o nome mesmo daquele atributo?

      public class Car{
          //... some code
          boolean isCarCrashed;
          //... some code
      }
    • Caso você veja o código a seguir, cuidado pois ele pode trazer muito entendimento incorreto:
          int value1, value2, value3;
          // ou
          String name1, name2, name3;

      O que poderia significar o um, dois ou três? Veja que em nenhum momento o atributo dá a entender onde deveria ser utilizado, e qual seria sua função. O código fica difícil de entender. Caso você tenha o azar de cair em if/else/while aninhados com esse tipo de atributo, é hora de levantar e ir pegar um café por que a tarde será longa… Imagine a seguinte situação:

          String str1, str2, str3, str4;
          //... some code
          str4 = str3.substring(4,8) + str1.concat(str2);

      Agora, imagine se o código tivesse sido escrito assim:

          String userLogin, userPassword, lastLoginDate, userAccessKey;
          //... some code
          userAccessKey = lastLoginDate.replaceAll("/", "-") + userLogin.concat("-" + userPassword);

      Conseguimos entender o que esse código está fazendo apenas pelos nomes dos atributos. Se estiver dentro de um método que tenha um nome claro então… Faz a combinação para deixar qualquer programador que leia o seu código feliz. Eu vi um caso em que semanticamente (pois era um estudo de OO) ao qual não haveria outra possibilidade de se colocar nomes que não tivesse 1 e 2 no final. Caso você tenha em mente o mesmo conceito e percepção, de que o projeto perderia coesão e sua definição se os atributos não tivessem o número no final, vá em frente e implemente seu código.

    • Os nomes dos atributos têm que sempre manter sentio ao contexto ao qual estão sendo utilizados. Sempre que ao ler o nome de um atributo ele tem que fazer sentido no trecho em que está aparecendo.
          //... some code
          int total = 0;
          for (Trade tradedBall : tratedBalls) {
              total += tradedBall.getTotalTratedItens();
          }
          for (Trade tratedHelmet : tratedHelmets) {
              total += tratedHelmet.getTotalTratedItens();
          }
          StockFacade stockFacade = FacadeFactory.getStockFacade();
          stockFacade.updateAmountTratedItens(total);
          //... some code in the same method
          //...
          //... 15 lines after
          double totalSpent = financialFacade.calculateSpentValue(spentValuesWithEmployees + (valuePerIten * total));
          return totalSpent;

      Quem é esse total que apareceu do nada ali no cálculo final? De onde veio esse valor? Qual o papel dele nesse método? Agora, imagina se ao invés de total fosse totalItensTrocados? Leia o código novamente trocando o total pelo nome sugerido.
      Essa é a diferença de se manter um nome que sempre tenha valor no contexto em que está sendo utilizado.

    • Não especificar na frente do nome do atributo o seu tipo. É muito comum se encontrar intIdade, strNome, dtNascimento. Você pode se perguntar: Que mal há nisso? Lembre que uma das boas práticas seria o fato do próprio nome do atributo se “auto-explicar”? Colocando o atributo na frente existem algumas desvantagens:
      • Incentivo às más nomenclaturas – é muito mais fácil pensar em colocar dtNascimento do que dataNascimento. Com isso, a idéia de nomes “auto-explicativos” iria começar a falhar. Poderiam nomes estranho como dtNas ou dtMNat (dataMorteNatural).
      • Variação na abreviação do tipo – seria fácil começar a encontrar algumas variações como: strNome, stNome, sNome, ou nmNome(se fosse apenas nome resolveria). Até aí nada de exagerado, agora imagine se sua aplicação tem um javascript e nele você começa a ver: cbDtIni ou então txNmCp. Qual seria a sua reação? Você saberia explicar cada um deles? Creia em mim, não é exagero, eu já vi atributos com esse tipo de nome.

      Evite esse tipo de prática, esse tipo de nome nos seu atributo irá causar uma leitura de código demorada e trabalhosa.

  • Já pensou em ter atributos de nomes pequenos e fáceis de digitar? Suponhamos que em seu programa você tenha uma variável chamada “todosOsAliensDoUniverso”. Agora imagine você tendo que digitar isso toda vez… Se bem que se essa variável se chamasse “aliens” seria… hum… Bem mais fácil de digitar e deu a entender que é uma lista. Não tem hora que você está fazendo aquele código legal e você pensa: “Caramba, tenho que digitar esse nome de novo?!”. Com um auto-completar hoje das IDEs tem ficado mais facil, mas imagine a pessoa ter que escolher entre 5 nomes toda hora, sendo que ela poderia estar a digitá-caso ele fosse pequeno…  Lembre-se, o nome de um atributo não deve afastar pessoas.
  • Espaço entre seus atributos – um código que envolva cálculos sem espaço entre seus atributos, fica um código que causa dor de cabeça! Vejamos um exemplo:
    total=salesPerDay(today)-(COMMITTEE_PERCENTAGE*vendors+totalSoldItens);

    Um código ganha mais clareza quando se tem espaços entre seus atributos:

    total = salesPerDay(today) - (COMMITTEE_PERCENTAGE * vendors + totalSoldItens);
  • Evitar o envio de atributos nulos – o envio de atributos nulos é a raiz de muitos nullPointers! Imagine só, você está acessando um método que nunca usou, mas falaram para você: “Vai lá, coloque o código chamando o método e envie o produto para o cliente. Pode confiar que esse método nunca deu erro!”. Só que não te explicaram que não poderia passar null. Com isso, uma imagem muito feia apareceria para o cliente e a confiança do cliente no programa ficaria afetada.

Bem pessoal, espero que esse artigo de hoje possa lhes ajudar.

Esse assunto terá continuação.

Até mais. [=