Ordenar Código

Si bien a la "maquina" le da lo mismo como esribamos nuestro código, sin dejar margen a la izquierda, ni donde es que colocamos nuestras llaves o comas y hasta podemos hacerlo todo en una solo línea

public class Hola
{public static void main (String[] args) {
String cadena = "Hola mundo"
;System.out.println(cadena)
;}}

Lo cierto es que a nosotros no, y la única razón es comprensión del mismo por cualquiera que acceda al código.

Por eso existen una serie de "Standars" para ordenar nuestro código :

Cada 1ra linea de bloque abrimos la llave al final del reglón { y deberá ser antecedido por un espacio.
Todo lo que esté dentro del bloque tendrá un margen de 4 espacios (Estos pueden ser 1 TAB ó 4 espacioes en blanco)
El final de cada instruccion termina con un punto y coma ;
Cada linea debería tener una longitud máxima de 80 caracteres, incluyendo los espacios adiciones creados por cada bloque.
Saltos de lineas creando renglones adicionales, son permitidos y recomendados para crear una mejor lectura.
la llave final de cierre del bloque } estará en una nueva linea al mismo nivel que de apertura.

public class OrdenarCodigo {
    public OrdenarCodigo() {
        super();
    }
    public static void main(String[] args) {
        new OrdenarCodigo();
    }
}

Guia de estilos

Lo cierto es que existen varias maneras de válidas de dar formato al código, y esta quedará en manos del grupo de trabajo. Si no se cuenta con una, la opción más recomendada es utulizar alguna third party como Google Java Style Guide (enalce) Estas se puede importar a nuestro editor de código para establecer un formato consisten a lo largo de toda la aplicación.

Comentarios

Estos sirven comentar el código, siendo ignorados por el compilador y asi cualquiera que acceda a nuestras lineas, incluso nosotros mismos, puedamos entender con facilidad para que sirven los bloques, declaraciones, variables, etc

Existen de varios tipos: Lineal, Multilineal, Comentarios en JSP y JavaDocs

Lineal

El comentario Lineal se hace con 2 barras laterales // y todo lo que vaya detrás de este, hasta el final de la linea no será tenido en cuenta por la máquina.

public class Comentarios {
    public static void main(String[] args) {
        //Las declaraciones del método main

    }//cierre del bloque Main
}//cierre del bloque Clase Comentarios

Multilineal

El comentario Multilineal se hace con una barra y un asterisco como apertura /* luego todo lo que siga (incluyendo saltos de linea) no será tenido en cuenta para nuestro programa hasta encontrar otro asterisco con una barra lateral */

public class Comentarios{
    public static void main(String[] args){
        /*El comentario multilineal
        puede encerar varias lineas
        que no serán tenidas en cuenta para nuestro código
        y sirven para explicar algunas lineas díficil
        de entender en primera instancias */
        //Desde luego se pueden combinar ambas en un mismo código

        String/*Builder*/ nombre = new String/*Builder*/("Dario");
    }//cierre del bloque Main
}//cierre del bloque Clase Comentarios

Comentarios en JSP

JSP es un motor de plantillas para crear páginas web, su trabajo consiste en tomar cada linea de código de archivos con extensión .jsp y transformarlos en código html que el navegador pueda entender.
Por ello, utiliza etiquetas especiales para entender que se trata de un comentario que debe ser ignorado en su procesamiento.

un comentario JSP. Ignorado por el motor JSP. No es visible en la máquina del cliente (Navegando el archivo fuente).
<%-- comment --%>
Un comentario HTML. Ignorado por el navegador pero es visible en la máquina cliente(Navegando en los archivos fuentes) como un comentario.
Comentario lineal en java. Ignorado por el compilador. No es visible en la máquina del cliente.
<% my code //my comment %>
Comentario multineal en java. Ignorado por el compilador. No es visible en la máquina del cliente.
1
2
3

<% my code /** my comment **/ %>

Java Docs

Estos se utilizan para generar documentación acerca de nuestro código, sólo pueden ser utilizados en clases, métodos, constructores, campos etc.
Para hacer uso de esta generación de documentación es necesario utiliza la herramienta javadoc.exe (se encuentra en nuestra instalación y será visible porque está incliuda en el PATH de nuestro sistema.)

Su sintaxis es similar a el comentario multilineal, con la excepción que al signo de apertura se le suma un nuevo asterisco /** y su signo de terminación es igual */
Para mayor lectura, cada nueva linea podría comenzar con un nuevo asterisco * aunque no es obligatorio.

/**
 * Esta Calculadora provee 2 metodos para sumar o dividir, 2 números dados
 * 
 * @author Dariojz
 */
public class Calculadora {
    /** Esta variable almacena el resultado de las operaciones */
    public static int resultado = 0;

    /**
     * Este método suma 2 números enteros
     * 
     * @return la suma de ambos
     */
    public static int sumar(int a, int b) {
        resultado = a + b;
        return resultado;
    }

    /**
     * Este método divide los números dados.
     * 
     * @throws ArithmeticException si el divisor es igual a 0.
     */
    public static int dividir(int dividendo, int divisor) throws ArithmeticException {
        resultado = dividendo / divisor;
        return resultado;
    }

}

Usos no recomendados

Otro utilidad de los comentarios son el de las pruebas, cuando querrarmos cambiar una pequeña parte de nuestro código o conservar parte de el, encerrarlo en comentarios lo hará invisible al compilador pero visible para el programador.

Una Taza de Java

Odernar Código y Comentarios