TUTORIAL DE JAVA (1): Consejos y comentarios.

Antes de seguir leyendo, debes de leerte uno de los post anteriores donde explico como instalar JDK.


Consejos previos:

Antes de empezar a programar, debemos de conocer una serie de conceptos y consejos para conseguir un buen programa y código.


Lo primero que debemos plantearnos es si nuestro programa va a ser privativo o lo vamos a compartir con otros programadores.


Si decidimos que el programa va a ser privativo y no queremos que nadie lo entienda, debemos de ofuscar el código, es decir, el nombre de las variables, métodos, campos, estados, excepciones, etc, no deben de ser claros. Ejemplo:


int x; (variable que va a ser la edad)

public void metodo1(int x); (método que aumentará la edad en +1)


Tampoco se debería comentar el código ni tabular el código.


Si por el contrario decimos que el código lo vamos a compartir con otros programadores o el caso de que no nos importe que sea legible, el código ha de ser claro y conciso.


El nombre de las variables, métodos, campos, estados, etc han de estar bien escritos:


int edad;

public void cumpleanios(int edad);


En este caso el código ha de estar bien comentado y correctamente tabulado.


Conociendo el entorno de java:


– Comentarios:

Para comentar el código, debemos ver el tipo de comentario que queremos hacer.


El primero que vamos a definir es el comentario en linea (//), el comentario no puede superar una línea. Se suele usar para comentar cosas que te quedan por hacer en el código o por hacer una breve aclaración de alguna línea de código.




public void cumpleanios(int edad){
    ++edad; // incrementar en uno la edad

}


Ahora pasemos a definir el comentario en bloque(/* comentario */), el comentario suele ser grande y para no hacer varios comentarios en linea, pasamos a hacer un solo comentario pero en bloque. Suele usarse para grandes comentarios dentro del código.


public void cumpleanios(int edad){

    /* En este comentario vamos a definir este método

    comentario comentario comentario comentario

    comentario comentario comentario comentario

    comentario comentario comentario comentario */

    ++edad;

}


El siguiente comentario que vamos a definir se suele usar para hacer un comentario formal e ilustrativo de nuestro código, haciendo de resumen de éste. Este comentario va a ser javadoc (/** comentario*/)


/**

* Programa de ejemplo para comentario javadoc

*

* @autor Emanuel Galván Fontalba

* @version 1.0

*/

public class Ejemplo(){
    public static void main(String [] args){

      //codigo

      //codigo

      //codigo

    }

}


Éste comentario requerirá generarlo más adelante y se genera un documento en HTML, el cual se puede visualizar más adelante.


-Conceptos generales:


Bloque de código:

Todo lo que va en un bloque de código, irá entre llaves ({ código }).


Cerrar lineas de código:

Líneas de código que no definen un bloque de código, se cerrará con punto y coma ( ; ).


Reglas generales de sintaxis:


-En el nombre de las variables, la primera letra es en minúscula.

-En el nombre de las clases, la primera letra es en mayúscula.

-En el nombre de métodos, la primera letra es minúscula.




Tras esta pequeña introducción pasamos a programar y establecer los comentarios correctamente:


/**

* Programa que muestra por pantalla “Hola mundo”

*

* @autor Emanuel Galván Fontalba

* @version 1.0

*/

public class HolaMundo(){ //Bloque de código
    public static void main(String [] args){
      System.out.println(“Hola mundo!!”); // Muestra por pantalla en consola

    }

}



Todo esto lo ejecutamos correctamente como se indica en la entrada donde comentamos como instalar JDK.

Documentación Javadoc de Oracle: Enlace