Posts com Tag ‘API’

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

ENV-006 – Introdução ao JDK

Publicado: 14/02/2014 por Ari Cesar em Básico, java
Tags:, , , , ,

Olá povo!

Nesse post iremos fazer uma breve introdução ao JDK apresentando seu conceito e dando de barbado alguns links de consulta.

O que é o JDK?

JDK é a abreviação para Java Development Kit ou em outras palavras é o nosso Kit de desenvolvimento de aplicativos java. Esse Kit de desenvolvimento é composto pela Java Virtual Machine (JVM), compilador da linguagem e uma série de códigos (bibliotecas) que nos auxiliam no desenvolvimento de aplicações.

A JDK vive em constante evolução e por isso que de tempos em tempos ( em torno de 2 anos) aparece uma nova versão. A versão atual é 7 e em março deve sair a 8 ( previsto para 18/3/2014).

É sempre aconselhável utilizar as ultimas versões do java, devido a ajustes finos feitos em sua JVM. De acordo com especialistas, códigos escritos em versões mais antigas da JVM são melhor executados em JVMs mais recentes, o que significa ganho de performance em seu sistema sem precisar refatorar o código.

Agora que já fizemos um overview, vamos entrar nos detalhes da JDK.

Compilador

Toda a linguagem tem o seu compilador e java não poderia ser diferente. Esse é o responsável por realizar a transformação do teu código .java em .class o que permite que seu código rode na JVM. Normalmente as IDEs fazem o trabalho de compilar os códigos desenvolvidos, mas caso você seja um amante do Rambo e queira colocar a sua faixa vermelha na cabeça, faca nos dentes e entrar selva a dentro, você pode realizar a compilação manual de sua classe ou pacote. Para isso precisa ir no promt do windows ou terminal do linux e digitar o tão famoso javac .

Java Virtual Machine (JVM)

Esse é o cara da antiga SUN, sem ele o Java não existiria (e isso não é exagero) . Ele é o responsável pela a interoperabilidade do seu código java em diversos sistemas operacionais. Como assim? Simples. Escreva uma vez o código, compile para bytecode e executar em qualquer Sistema Operacional que tenha JVM instalado. Lembrando que isso incluir dispositivos móveis e outros sistemas embarcados como por exemplo o painel de controle de seu carro ou do avião que você vai pegar para viajar.
Maravilho certo? Agora voltando ao nosso JDK. A JVM vai ser o responsável por executar o teu código em sua maquina. Quando se trata da JVM nunca podemos nos esquecer dos seguintes detalhes:

  • A JVM simula um sistema operacional por isso que os byteCode rodam sem problema em qualquer lugar do universo (continua não sendo exagero porque tem robo da NASA em marte rodando Java).
  • A JVM não roda apenas java, ela também roda Grovy, JavaScript e outras linguagens.

Estamos planejando fazer um post específico sobre a JVM, então aguardem que será bem interessante

Bibliotecas (API)

Você ja programou em Java alguma vez? Caso a resposta seja sim, com certeza você já utilizou alguma biblioteca do Java. Como assim? Java tem uma penca de códigos internos, oque chamamos de API do Java. Essas APIs são divididas para Java SE , Java ME e Java EE e tem suas questões específicas. Se algum dia você digitou System.out.println("Olá mundo") para escrever no console Olá Mundo, te informo que já teve contato com a API do Java.

Te digo mais, é impossível programar em java sem utilizar a API deles. Sendo assim te aconselho a dar uma estuda na API do JAVA. É costume de muitos programadores ficar criando códigos que já existem na API, ou até pior, não estudar a API por não entendê-la.

Bom, era isso. Espero que esse post tenha ajudado a entender melhor o java.

Abraços a todos e até a próxima.