FEA-DOC-001 – JavaDocs o que são e para que servem

Publicado: 04/03/2014 por Ari Cesar em Básico, java
Tags:, , , ,

E ai galera do Java, tranquilo?

Hoje vamos tratar de algo que é super simples, mas de extrema importância no mundo java…. Os tão famosos javadoc.

O que são javadoc?

Javadoc é aquela documentação que utilizamos em cima de classes, métodos e atributos e servem para identificar sua funcionalidade. Para ficar mais claro, vamos ver um exemplo de código:

package javaapplication1;

public class Calcular {
    private Double valor1;
    private Double valor2;

    public Double somar(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 + valor2;
        return calculo;

    }
    public Double subtrair(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 - valor2;
        return calculo;

    }
    public Double multiplicar(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 * valor2;
        return calculo;

    }
    public Double dividir(Double valor1, Double valor2){
        Double calculo = 0.0;
        if (valor2 != 0){
            calculo = valor1 / valor2;
        }
        else {
            System.out.println("ERRO! Divisão por 0!");
        }


        return calculo;
    }

    public Double calcularComplexo(Double valor1, Double valor2){
      Double calculo = 0.0;  
        // faz calculos que apenas de pensar dai a nossa cabeça
        return calculo;
    }

    public Double getValor1() {
        return valor1;
    }

    public void setValor1(Double valor1) {
        this.valor1 = valor1;
    }

    public Double getValor2() {
        return valor2;
    }

    public void setValor2(Double valor2) {
        this.valor2 = valor2;
    }    
}

Ok, o exemplo de código é bem simples e parece não precisar de nenhum tipo de explicação, certo? Temos ai o nossas variáveis de classe, seus gets e sets e alguns métodos, todos simples fazendo a soma, subtração, divisão, multiplicação e ….. calcularComplexo? O que esse método faz? Quais são esses números? O que ele retorna? Se você for o programador do método irá saber o que ele faz, mas se você for o utilizador do método e não tiver acesso ao código fonte? Ou pior, tem acesso ao código, mas não consegue entender o que ele faz? Para ter uma ideia do que cada método faz terá que ir testando eles como abaixo.

package javaapplication1;

public class JavaApplication1 {

    public static void main(String[] args) {
     Calcular calc = new Calcular();

        System.out.println("Divisão: " + calc.dividir(5.0, 12.0));
        System.out.println("Multiplicação: " + calc.multiplicar(23.0, 2.0));
        System.out.println("Subtração: " + calc.subtrair(2.0, 3.0));
        System.out.println("adição: " + calc.somar(7.0, 6.0));
        System.out.println("Calculo complexos: " + calc.calcularComplexo(1.0, 6.0));

    }

}

Vamos ser sinceros, é inaceitável ter que criar um novo projeto para entender os métodos.

Bom, esse código é uma brincadeira, mas é uma realidade do mercado do desenvolvimento onde muitos programadores não documentam o código devido a pressão dos prazos ou por pura preguiça. Hoje o mercado de desenvolvimento possui diversas ferramentas para avaliar a qualidade de código e entre as análises está a cobertura de documentação no código o que significa que documentar o código (inserir javadocs) é uma boa prática de desenvolvimento.

Agora vamos ver o código documentado com os javadoc.

package javaapplication1;

/**
 *Classe especialista na realização de calculos de matemática.
 * @author aricesar
 */
public class Calcular {


    private Double valor1;
    private Double valor2;

    /**
     * Método que executa a soma de dois valores sejam eles positivos ou negativos.
     * 
     * @param valor1 - > valor Double
     * @param valor2 - > valor Double
     * @return valor calculado (tipo Double)
     */
    public Double somar(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 + valor2;
        return calculo;
    }


    /**
     * Método que executa a subtração de dois valores sejam eles positivos ou negativos.
     * @param valor1 - > valor Double
     * @param valor2 - > valor Double
     * @return valor calculado (tipo Double)
     */
    public Double subtrair(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 - valor2;
        return calculo;
    }

    /**
     * Método que executa a multiplicação de dois valores sejam eles positivos ou negativos.
     * @param valor1 - > valor Double
     * @param valor2 - > valor Double
     * @return valor calculado (tipo Double)
     */
    public Double multiplicar(Double valor1, Double valor2){
        Double calculo = 0.0;
        calculo = valor1 * valor2;
        return calculo;

    }

    /**
     * Método que executa a divisão de dois valores sejam eles positivos ou negativos. 
     * Impede o erro de divisão por zero.
     * @param valor1 - > valor Double
     * @param valor2 - > valor Double ( não pode ser zero)
     * @return valor calculado (tipo Double)
     */
    public Double dividir(Double valor1, Double valor2){
        Double calculo = 0.0;
        if (valor2 != 0){
            calculo = valor1 / valor2;
        }
        else {
            System.out.println("ERRO! Divisão por 0!");
        }


        return calculo;
    }

    /**
     * Executa calculos complexos subtraindo, dividindo, multiplicando e somando os valores passados por parametro. Pode retornar qualquer valor.
     * 
     * @param valor1 - > valor Double
     * @param valor2 - > valor Double
     * @return valor calculado (tipo Double)
     */
    public Double calcularComplexo(Double valor1, Double valor2){
      Double calculo = 0.0;  
      // faz calculos que apenas de pensar dai a nossa cabeça
        return calculo;
    }

    /**
     * Getter do valor 1
     * @return valor 1
     */
    public Double getValor1() {
        return valor1;
    }

    /**
     * Setter do valor 1
     * @param valor1 
     */
    public void setValor1(Double valor1) {
        this.valor1 = valor1;
    }

    /**
     * Getter do valor 2
     * @return valor 2
     */
    public Double getValor2() {
        return valor2;
    }

    /**
     * Setter do valor 2
     * @param valor2
     */
    public void setValor2(Double valor2) {
        this.valor2 = valor2;
    }

}

Melhorou? Agora quando alguém for utilizar o código da classe Calcular os comentários serão apresentados e o programador saberá o que faz cada um dos métodos.

Quer ver funcionando? Crie um projeto, crie uma classe chamada Calcular e copie esse último código que possui os comentários. Depois crie uma nova classe e copie o código abaixo para dentro dela.

    public static void main(String[] args) {
     Calcular calc = new Calcular();

    }

Depois disso, faça o import necessário para funcionar a classe Calcula e escreva calc. (se precisar use CTRL+ para ativar o autocomplete). Escolha algum dos métodos da classe Calcular e verá o javadoc que criamos para ele.

Uma ultima observação de qualidade de código: Um bom método é auto-explicativo o que significa que o nome do método e seu javadoc devem ser mais do que suficientes para explicar o que ele é e o que faz. Nunca, em hipótese alguma, um programador deve necessitar acessar o código do método para entender para que ele serve, Esse tipo de coisa caracteriza um método mal documentando ou com problema de nomenclatura.

Se quer um bom exemplo de documentação de uma olhada nós códigos nativos do java. Você verá que cada classe e método possuiu seu javadoc.

Bem, é isso, até a próxima.

Anúncios

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s