PDF de programación - Convenciones de código para Java

Convenciones de código para Java


1 - Introducción

1.1 ¿Por qué tener convenciones de código?

Las convenciones de código son importantes para los programadores por un gran número
de razones:


 El 80% del coste del código de un programa va a su mantenimiento.
 Casi ningún software lo mantiene toda su vida el autor original.
 Las convenciones de código mejoran la lectura del software, permitiendo a los

ingenieros entender nuevo código mucho más rápido y más a fondo.

 Si distribuyes tu código fuente como un producto, necesitas asegurarte de que está

bien hecho y presentado como cualquier otro producto.


Para que funcionen las convenciones, TODOS los programadores deben seguirlas.

1.2 Agradecimientos

Este documento refleja los estándares de codificación del lenguaje Java presentados en
Java Language Specification , de Sun Microsystems, Inc. Los mayores contribuidores son
Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath, y Scott
Hommel.

Este documento es mantenido por Scott Hommel. Enviar los comentarios a
[email protected]

2 - Nombres de ficheros

Esta sección muestra las extensiones y nombres de ficheros más comúnmente usadas.

2.1 Extensiones de los ficheros

El software Java usa las siguientes extensiones para los ficheros:

Tipo de archivo

Extensión

Fuente Java
Bytecode de Java

.java
.class



1


2.2 Nombres comunes para ficheros

Los nombres de ficheros más utilizados incluyen:

Nombre de fichero
GNUmakefile

README



Uso
El nombre preferido para ficheros "make". Usamos
gnumake para construir nuestro software.
El nombre preferido para el fichero que resume los
contenidos de un directorio particular.

3 - Organización de los ficheros

Un fichero consiste de secciones que deben estar separadas por líneas en blanco y
comentarios opcionales que identifican cada sección.

Los ficheros de más de 2000 líneas son incómodos y deben ser evitados.

Para ver un ejemplo de un programa de Java debidamente formateado, ver "Ejemplo de
fichero fuente Java" en la página 20.

3.1 Ficheros fuente Java

Cada fichero fuente Java contiene una única clase o interfaz pública. Cuando algunas clases
o interfaces privadas están asociadas a una clase pública, pueden ponerse en el mismo
fichero que la clase pública. La clase o interfaz pública debe ser la primera del fichero.

Los ficheros fuentes Java tienen la siguiente ordenación:


 Comentarios de comienzo (ver "Comentarios de comienzo" en la página 2).
 Sentencias Package e Import.
 Declaraciones de clases e interfaces (ver "Declaraciones de clases e interfaces" en la

página 3).


3.1.1 Comentarios de comienzo

Todos los ficheros fuente deben comenzar con un comentario (al estilo lenguaje C) en el
que se muestra el nombre de la clase, información de la versión, fecha, y copyright:

/*
* Nombre de la clase

*
* Información de la version

*
* Fecha



2

*

* Copyright
*/


3.1.2 Sentencias Package e Import

La primera línea de los ficheros fuente Java que no sea un comentario, es la sentencia
package. Después de ésta, pueden seguir varias sentencias import. Por ejemplo:


package java.awt;

import java.awt.peer.CanvasPeer;


3.1.3 Declaraciones de clases e interfaces

La siguiente tabla describe las partes de la declaración de una clase o interfaz, en el orden
en que deberían aparecer. Ver "Ejemplo de fichero fuente Java" en la página 20 para un
ejemplo que incluye comentarios.


Partes de la declaración de

Notas

una clase o interfaz

1 Comentario de documentación de

la clase o interfaz (/**...*/)

2 Sentencia class o interface

3 Comentario de implementación de

la clase o interfaz si fuera necesario
(/*...*/)

4 Variables de clase (static)

5 Variables de instancia

6 Constructores

7 Métodos

Ver "Comentarios de documentación" en la página 8 para
más información sobre lo que debe aparecer en este
comentario.



Este comentario debe contener cualquier información
aplicable a toda la clase o interfaz que no era apropiada
para estar en los comentarios de documentación de la
clase o interfaz.

Primero las variables de clase public, después las
protected, después las de nivel de paquete (sin
modificador de acceso), y después las private.

Primero las public, después las protected, después las
de nivel de paquete (sin modificador de acceso), y
después las private.


Estos métodos se deben agrupar por funcionalidad más
que por visión o accesibilidad. Por ejemplo, un método de
clase privado puede estar entre dos métodos públicos de
instancia. El objetivo es hacer el código mas legible y
comprensible.



3

4 – Indentación

Se deben emplear cuatro espacios como unidad de indentación. La construcción exacta de
la indentación (espacios en blanco contra tabuladores) no se especifica. Los tabuladores
deben ser exactamente cada 8 espacios (no cada 4).

4.1 Longitud de la línea

Evitar las líneas de más de 80 caracteres, ya que no son manejadas bien por muchas
terminales y herramientas.

Nota: Ejemplos para uso en la documentación deben tener una longitud inferior,
generalmente no más de 70 caracteres.

4.2 Rompiendo líneas

Cuando una expresión no entre en una línea, romperla de acuerdo con estos principios:


 Romper después de una coma.
 Romper antes de un operador.
 Preferir roturas de alto nivel que de bajo nivel.
 Alinear la nueva línea con el comienzo de la expresión al mismo nivel de la línea

anterior.

 Si las reglas anteriores llevan a código confuso o a código que se aglutina en el

margen derecho, indentar justo 8 espacios en su lugar.


Ejemplos de como romper la llamada a un método:


unMetodo(expresionLarga1, expresionLarga2, expresionLarga3,

expresionLarga4, expresionLarga5);



var = unMetodo1(expresionLarga1,

unMetodo2(expresionLarga2,

expresionLarga3));


Ahora dos ejemplos de ruptura de líneas en expresiones aritméticas. Se prefiere el primero,
ya que el salto de línea ocurre fuera de la expresión que encierra los paréntesis.


nombreLargo1 = nombreLargo2 * (nombreLargo3 + nombreLargo4

- nombreLargo5) + 4 * nombreLargo6; // PREFERIDA



nombreLargo1 = nombreLargo2 * (nombreLargo3 + nombreLargo4

- nombreLargo) + 4 * nombreLargo6; // EVITAR


Ahora dos ejemplos de indentación en declaraciones de métodos. El primero es el caso
convencional. El segundo conduciría la segunda y la tercera línea demasiado hacia la



4

izquierda con la indentación convencional, así que en su lugar se usan 8 espacios de
indentación.


//INDENTACION CONVENCIONAL
unMetodo(int unArg, Object otroArg, String todaviaOtroArg,

Object yOtroMas) {

...
}


//INDENTACION DE 8 ESPACIOS PARA EVITAR GRANDES INDENTACIONES

private static synchronized metodoDeNombreMuyLargo(int unArg,

Object otroArg, String todaviaOtroArg,
Object yOtroMas) {

...

}



La ruptura de líneas para sentencias if deberá seguir generalmente la regla de los 8
espacios, ya que la indentación convencional (4 espacios) hace difícil ver el cuerpo. Por
ejemplo:


//NO USAR ESTA INDENTACION

if ((condicion1 && condicion2)

|| (condicion3 && condicion4)

||!(condicion5 && condicion6)) { //MALOS SALTOS
hacerAlgo(); //HACEN ESTA LINEA FACIL DE OLVIDAR

}


// USAR ESTA INDENTACION

if ((condicion1 && condicion2)

|| (condicion3 && condicion4)
||!(condicion5 && condicion6)) {

hacerAlgo();

}


//O USAR ESTA
if ((condicion1 && condicion2) || (condicion3 && condicion4)

||!(condicion5 && condicion6)) {

hacerAlgo();

}


Hay tres formas aceptables de formatear expresiones ternarias:


alpha = (unaLargaExpresionBooleana) ? beta : gamma;


alpha = (unaLargaExpresionBooleana) ? beta

: gamma;



alpha = (unaLargaExpresionBooleana)

? beta

: gamma;






5

5 – Comentarios

Los programas Java pueden tener dos tipos de comentarios: comentarios de
implementación y comentarios de documentación. Los comentarios de implementación son
aquellos que también se encuentran en C++, delimitados por /*...*/, y //. Los comentarios
de documentación (conocidos como "doc comments") existen sólo en Java, y se limitan por
/**...*/. Los comentarios de documentación se pueden exportar a ficheros HTML con la
herramienta javadoc.

Los comentarios de implementación son para comentar nuestro código o para comentarios
acerca de una implementación particular. Los comentarios de documentación son para
describir la especificación del código, libre de una perspectiva de implementación, y para
ser leídos por desarrolladores que pueden no tener el código fuente a mano.

Se deben usar los comentarios para dar descripciones de código y facilitar información
adicional que no es legible en el propio código. Los comentarios deben contener sólo
información que es relevante para la lectura y entendimiento del programa. Por ejemplo,
información sobre cómo se construye el paquete correspondiente o en qué directorio reside,
no debe ser incluida como comentario.

Son apropiadas las discusiones sobre decisiones de diseño no triviales o no obvias, pero
evitan duplicar información que esta presente (de forma clara) en el código ya que es fácil
que los comentarios redundantes se queden desfasados. En general, evitar cualquier
comentario que pueda quedar desfasado a medida que el código evoluciona.

Nota: La frecuencia de comentarios a veces refleja una pobre calidad del código. Cuando
se sienta obligado a escribir un comentario, considere rescribir el código para hacerlo más
claro.

Los comentarios no deben encerrarse en grandes cuadrados dibujados con asteriscos u otros
caracteres.
Los comentarios nunca deben incluir caracteres especiales como backspace.

5.1 Formatos de los comentarios de implementación

Los programas pueden tener cuatro estilos de comentarios de implementación: de bloque,
de una línea,