PDF de programación - Convenciones de Código Java

Publicado en jpereza (http://jpereza.nom.es)
Creado 10/01/2008 - 17:39 Por jpereza
Java

Convenciones de Código Java
Traducción del artículo original de Sun Microsystems, Inc. Code Conventions for the JavaTM
Programming Language [1].
Por qué tener convenciones de código
Las convenciones de código son importantes para los programadores por numerosas razones:

El 80% del tiempo de vida de un programa se dedica al mantenimiento del mismo.
En pocas ocasiones, el programa es mantenido durante toda su vida útil por su autor original.
Las convenciones de código aumentan la legibilidad de los programas, permitiendo a los
desarrolladores comprender nuevo código rápida y perfectamente.
Si se distribuye el código fuente como un producto, se necesita asegurar que está tan bien
empaquetado y limpio como cualquier otro producto que se cree.

Reconocimientos
Este documento refleja los estándares de codificación del lenguaje Java presentados en la
Especificación del Lenguaje Java [2], de Sun Microsystems, Inc. Sus principales contribuciones son de
Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath y Scott Hommel.
Cualquier comentario sobre el documento original (en inglés) debería ser enviado a Sun
Microsystems, Inc. a través del siguiente formulario de contacto [3].
Cualquier comentario sobre esta traducción debería ser enviado a Jesús Pérez Alcaide [4].

Nombres de fichero

Esta sección lista los nombres de fichero y sufijos usados comúnmente.
Sufijos de fichero
Java utiliza los siguientes sufijos de fichero:

Sufijo
Tipo de fichero
Código fuente Java
.java
Código compilado Java .class

Nombres de ficheros comunes

Nombre de
fichero

LEEME

Uso

Nombre preferido para el fichero que resume el contenido de un directorio en
particular.

Organización de ficheros

Un fichero consiste en secciones que deberían estar separadas por líneas en blanco y un comentario
opcional identificando cada sección.
Los ficheros de más de 2000 líneas son demasiado largos y deberían evitarse.
Para ver un ejemplo de un programa Java correctamente formado, ir al Ejemplo de código fuente Java
[5].
Ficheros de código fuente Java
Cada fichero de código fuente Java contiene una única clase o interfaz público. Cuando una clase
pública tiene clases privadas e interfaces asociados, se pueden poner en el mismo fichero de código
fuente que la clase pública. La clase pública debería ser la primera clase o interfaz en el fichero.
Los ficheros de código fuente Java tienen la siguiente ordenación:

Comentarios iniciales
Sentencias package e import
Declaraciones de clase e interfaz

Comentarios iniciales
Todos los ficheros de código fuente deberían comenzar con un comentario que muestre el nombre de
la clase, información sobre la versión, la fecha y el copyright.
/*
* Nombre de la clase
*
* Información sobre la versión
*
* Fecha
*
* Copyright
*/
Sentencias package e import
La primera línea que no sea un comentario de todos los ficheros de código fuente Java es una

sentencia package. Después, puede haber sentencias import. Por ejemplo:
package es.nom.jpereza;
import java.util.List;
Nota: El primer componente de un nombre de paquete único estaría siempre escrito en letras ASCII
minúsculas y sería uno de los nombres de dominio de nivel superior (actualmente com, edu, gov, mil,
net, org ó uno de los códigos de país de dos letras, como se especifica en el estándar ISO 3166 [6]).
Declaraciones de clase e interfaz
La siguiente tabla describe las partes de una declaración de clase o interfaz, en el orden que deben
aparecer. En Ejemplo de código fuente Java [5] hay un ejemplo que incluye comentarios.
Parte de la declaración de

Notas

Clase/Interfaz
Comentario de documentación
de la clase/interfaz
(/** ... */)

1

Ver Comentarios [7] para más información sobre el contenido
de este comentario.

2 Sentencia class ó interface



3

Comentario de la
implementación de la
clase/interfaz, si fuera
necesario
(/* ... */)

4 Variables de clase (estáticas)

(static)

5 Variables de instancia

6 Constructores

7 Métodos

Tabulación

Este comentario debería contener cualquier información
relativa a toda la clase o interfaz, que no sea apropiada para el
comentario de documentación.

Primero las variables públicas (public), luego las protegidas
(protected), después las de paquete (sin modificador de
acceso) y por último las privadas (private).
Primero las variables públicas (public), luego las protegidas
(protected), después las de paquete (sin modificador de
acceso) y por último las privadas (private).

Estos métodos deberían estar agrupados por funcionalidad en
lugar de por ámbito o accesibilidad. Por ejemplo, un método
estático privado puede estar entre dos métodos de instancia
públicos.
El objetivo es hacer la lectura y comprensión del código más
fácil.

La unidad de tabulación deberían ser cuatro espacios. La forma exacta de la tabulación (espacios ó
tabuladores) no se especifica.
Longitud de línea
Evitar las líneas de más de 80 caracteres, ya que algunas herramientas no las manejan bien.
Nota: Ejemplos para uso en documentación deberían tener una longitud de línea menor, generalmente
no más de 70 caracteres.
Ruptura de líneas (Wrapping lines)
Cuando una expresión no cabe en una única línea, se debe romper de acuerdo a estos principios
generales:

Romper después de una coma.
Romper antes de un operador.
Preferir las rupturas de alto nivel a las de bajo nivel.
Alinear la nueva línea con el principio de la expresión al mismo nivel que la línea anterior.
Si las reglas anteriores llevan a un código confuso o demasiado pegado al margen derecho,
entonces tabular sólo con 8 espacios.

Aquí hay algunos ejemplos de llamadas a métodos en varias líneas:
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);

var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));
A continuación, dos ejemplos de cómo romper una expresión aritmética. El primero es más
recomendable, puesto que la ruptura ocurre fuera de la expresión entre paréntesis, la cual es de mayor
nivel.
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; // RECOMENDADA

longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; // EVITAR
A continuación hay dos ejemplos de cómo tabular declaraciones de métodos. El primero es el caso
convencional. El segundo dejaría la segunda y tercera líneas demasiado pegadas al margen derecho si
se usara la tabulación convencional, por eso en cambio se tabula sólo con 8 espacios.
// TABULACION CONVENCIONAL
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}

// USAR 8 ESPACIOS PARA EVITAR PEGARSE AL MARGEN DERECHO
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,

Object andStillAnother) {
...
}
La ruptura de líneas para las sentencias if debería usar generalmente la regla de los 8 espacios, ya
que la tabulación convencional (4 espacios) dificulta la lectura del cuerpo de la sentencia if. Por
ejemplo:
// NO UTILIZAR ESTA TABULACION
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { // MALAS RUPTURAS
doSomethingAboutIt(); // HACEN QUE ESTA LINEA SE PIERDA FACILMENTE
}

// USAR ESTA TABULACION EN SU LUGAR
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}

// O USAR ESTA OTRA
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
Aquí se muestran tres maneras aceptables de escribir expresiones ternarias:
alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
: gamma;

alpha = (aLongBooleanExpression)
? beta
: gamma;

Comentarios

Los programas en Java pueden tener dos tipos de comentarios: comentarios de implementación y
comentarios de documentación. Los comentarios de implementación son como los de C++, los cuales
están delimitados por /* ... */ y //. Los comentarios de documentación (conocidos como
"comentarios Javadoc") son específicos de Java y están delimitados por /** ... */. Los comentarios
de documentación se pueden extraer a ficheros HTML usando la herramienta javadoc.
Los comentarios de implementación están destinados a comentar el código o para comentarios sobre
la implementación en particular. Los comentarios de documentación están destinados a describir la
especificación del código, desde una perspectiva independiente de la implementación, para ser leídos
por desarrolladores que pueden no tener necesariamente el código fuente a mano.
Los comentarios se deberían usar para dar una visión general del código y para proporcionar
información adicional que no esté disponible fácilmente en el propio código. Los comentarios
deberían contener solamente información que sea relevante para la lectura y comprensión del

programa. Por ejemplo, información sobre cómo se construye el paquete correspondiente o en qué
directorio reside, no debería ser incluida como comentario.
Discusiones sobre decisiones de diseño que no sean obvias o triviales son apropiadas, pero evitar
duplicar información que esté presente (y de forma clara) en el código. Es muy fácil que los
comentarios redundantes expiren. En general, evitar cualquier comentario que sea probable que expire
según evoluciona el código.
Nota: La frecuencia de los comentarios a veces refleja la pobre calidad del código. Cuando te sientas
obligado a añadir un comentario, considera reescribir el código para hacerlo más claro.
Los comentarios no deberían estar encerrados en grandes cajas dibujadas con asteriscos u otros
caracteres.
Los comentarios no deberían incluir nunca caracteres especiales como el avance de página (códig