Convenciones de Codificación en Java

(recomendaciones de Sun ©)

Identación
Se deberían usar 8 espacios como unidad de identación.

Longitud de Línea
Evitar líneas máyores de 80 caracteres, ya que no son bien manejadas por muchos terminales y
herramientas.

Ruptura de Líneas
Cuando una expresión no entre en una sóla línea, se debe dividir de acuerdo a estos principios
generales:
después de una coma.
antes de un operador.
alinear la nueva línea con el principio de la expresión al mismo nivel de la línea anterior.

Ejemplos:
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);

longName1 = longName2 * (longName3 + longName4 - longName5)

+ 4 * longname6; // PREFER

if ((condition1 && condition2)

|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}

alpha = (aLongBooleanExpression)
? beta
: gamma;

Comentarios

Comentarios
Los programas Java pueden tener dos tipos de comentarios: los comentarios de implementación y
los comentarios de documentación. Los comentarios de implementación son aquellos encontrados
en C++, que están delimitados por /*...*/, y //. Los comentarios de documentación son únicos 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 se han creado para comentar código o para comentarios sobre
la implementación particular. Los comentarios de documentación se han creado para definir la
especificación del codigo, desde un perspectiva libre de implementación para ser leído por
desarrolladores que podrían no tener necesariamente a mano el código fuente.
Los comentarios deberían usarse para una introducción del código y proporcionar información
adicional que no está disponible en el propio código. Los comentarios sólo deberían tener
información que sea relevante para leer y entender el programa. Por ejemplo, información sobre
como está construido el paquete correspondiente o en qué directorio reside no debería ser incluida
como comentarios.

Las discusiones no triviales o decisiones de diseño no obvias son apropiadas, pero debemos evitar
la duplicidad de información que esté presente en el código. Es fácil que los comentarios
redundantes se queden anticuados. En general, debemos evitar cualquier comentario que se pueda
quedar anticuado cuando el código evolucione.

Nota:
La frecuencia en los comentarios algunas veces refleja una pobre calidad de código. Cuando nos
sintamos obligados a llenarlo de comentarios, debemos considerar la reescritura del código para
hacerlo más claro. Los comentarios no deben encerrarse en grandes cajas dibujadas con asteriscos u
otros caracteres. Los comentarios nunca deberían incluir caracteres especiales como saltos de
página, etc.

Los programas pueden tener cuatro estilos de implementación de comentarios:

Bloque de Comentarios
Los bloques de comentarios se usan para proporcionar descripciones de ficheros, métodos,
estructuras de datos y algoritmos. Los bloques de comentarios podrían usarse al principio de cada
fichero y antes de cada método. También pueden usarse en otros lugares, como dentro de los
métodos. Los bloques de comentarios dentro de una función o métodos deberían estar identados al
mismo nivel que el código que describen. Un bloque de comentario debería ir precedido por una
línea en blanco para configurar un apartado del resto del código:

/*
* Here is a block comment.
*/
Los bloques de comentarios pueden comenzar con /*-, lo que le dice al indent(1) que es el principio
de un bloque de comentarios y que no debería ser reformateado, por ejemplo:

/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
* one
* two
* three
*/
Nota:
Si no usamos indent(1), no tenemos que usar /*- en nuestro código o hacer cualquier otra concesión
a la posibilidad de que alguién pudiera ejecutar indent(1) sobre nuestro código.
Cómentarios de una línea
Los comentarios cortos pueden aparecen como uná sóla línea identada al nivel del código que la
sigue. Si un comentario no se puede escribir en una sóla línea, debería seguir el formato de los
bloques de comentario. Un comentario de una sóla línea debería ir precedido de una línea en blanco.
Aquí tenemos un ejemplo:

if (condition) {

/* Handle the condition. */

...
}

Comentarios finales
Los comentarios muy cortos pueden aparecer en la misma línea que el código que describen, pero
deberían separarse lo suficiente de las sentencias. Si aparece más de un comentario en el mismo
trozo de código, deberían estar identados a la misma altura. Aquí tenemos un ejemplo:

if (a == 2) {
return TRUE; /* special case */
} else {
return isPrime(a); /* works only for odd a */
}
Comentarios de final de línea
El delimitador de comentario // puede comentar una línea completa o una línea parcial. No debería
usarse en líneas consecutivas para comentar texto; sin embargo, si puede usarse en líneas
consecutivas para comentar secciones de código. Abajo tenemos ejemplos de los tres estilos:

if (foo > 1) {
// Do a double-flip.
...
}
else{
return false; // Explain why here.
}

//if (bar > 1) {

//
// // Do a triple-flip.
// ...
//}
//else{
// return false;
//}

Comentarios de Documentacion
Los comentarios de documentación describen clases Java, interfaces, constructores, métodos y
campos. Cada comentario de documentación va dentro de los delimitadores de comentario /**...*/,
con un comentario por clase, interface o miembro. Este comentario debe aparecer justo antes de la
declaración:
/**
* The Example class provides ...
*/
public class Example { ...
Observa que las clases e interfaces de alto nivel no están identados, mientras que los miembros si lo
están. La primera línea del comentario de documento (/**) para las clases e interfaces no está
identada; las subsecuentes líneas del comentario de documentación tendrán un espacio de
identación (para alinear verticalmente los astericos). Los miembros, incluyendo constructores,
tienen cuatro espacios para la primera línea de comentario de documentación y 5 espacios después.

Si necesitamos dar información sobre una clase, un interface, una variable o un método que no es
apropiada para documetnación, usamos una implementación de bloque de comentario, o una
declaración de una línea inmediatamente después de la declaración. Por ejemplo, los detalles sobre
la implementación de una clase deberían ir en un bloque de comentario seguido por la sentencia
class, no en el comentario de documentación de la clase.

Los comentarios de documentación no deberían colocarse dentro de un bloque de definición de un

método o constructor porque Java asocia los comentarios de documetnación con la primera
declaración que hay después del comentario...

Declaraciones

Número de declaraciones por línea

Se recomienda una declaración por línea ya que mejora los comentarios. En otras palabras:

int level; // indentation level

int size; // size of table
se prefiere sobre:

int level, size;

No debemos poner diferentes tipos en la misma línea. Por ejemplo:

int foo, fooarray[]; //WRONG!

Nota:
Los ejemplos de arriba usan un espacio entre el tipo y el identificador. Otra alternativa aceptable es
usar tabs, por ejemplo:

int level; // indentation level

int size; // size of table
Object currentEntry; // currently selected table entry

Inicialización
Debemos intentar inicializar las variables locales donde son declaradas. La única razón para no
inicializar una variable donde es declarada es si el valor inicial depende de algún cálculo que tiene
que ocurrir antes.
Situación
Ponemos las declaraciones sólo al principio de los bloques. (Un bloque es cualquier código
encerrado entre corchetes “{” y “}”.) No debemos esperar a declarar variables hasta que son usadas
por primer vez; puede confundir la programador despistado y estorbar la portabilidad del código
dentro del ámbito.

void myMethod() {
int int1 = 0; // beginning of method block

if (condition) {
int int2 = 0; // beginning of "if" block
...
}
}
La única excepción a esta regla son los indexados para los bucles, que en Java pueden ser
declarados en la sentencia for:

for (int i = 0; i < maxLoops; i++) { ... }

Debemos evitar las declaraciones locales que oculten las declaraciones de nivel superior. Por
ejemplo, no debemos declarar el mismo nombre de variable en un bloque interno:

int count;
...
myMethod() {
if (condition) {
int count; // AVOID!
...
}
...
}

Declaraciones de Clases e Interfaces

Cuando codificamos clases e interfaces Java, se deben seguir las siguientes reglas de formateo:

No debe haber ningún espacio entre el nombre y el paréntesis “(“ que inicia la lista de parámetros.
El corchete abierto “{” aparece en la misma línea que la declaración.
El corchete cerrado “}” empieza una línea por sí mismo, identado a su correspondiente sentencia de
apertura, excepto cuando es una sentencia null en la que el “}” debería aparecer inmediatamente
después del “{“:
class Sample extends Object {
int ivar1;
int ivar2;

Sample(int i, int j) {
ivar1 = i;
ivar2 = j;
}

int emptyMethod() {}
...
}

Los métodos están separados por una línea en blanco.

Sentencias

Sentencias Simples
Cada línea debe contener como máximo una sentencia. Por ejemplo:

argv++; // Correct
argc++; // Correct
argv++; argc--; // AVOID!

Sentencias Compuestas
Las sentencias compuestas son sentencias que contienen listas de sentencias encerradas entre
corchetes “{ sentencias }”. Puedes ver ejemplos en las siguientes secciones.

Las sentencias encerradas deben identarse uno o más niveles que la sentencia compuesta.
El corchete de apertura debe estar al final de la línea que empieza la sentencia compuesta; el
corchete de cierre debería empezar una nueva línea y estar identado con el principio de la sentencia
compuesta.
Los corchetes se usan alrededor de todas las sentencias, incluso para sentencias simples, cuando
éstas forman parte de una estructura de control como una sentencia if-else o for. Esto hace más fácil
la adición de sentencias sin introducir errores debido al olvido de los corchetes.

Sentencias de Retorno
Una sentencia de retorno no debería usar paréntesis a menos que el valor de retorno sea más óbvio
de esa forma. Por ejemplo:

return;
return myDisk.size();
return (size ? size : defaultSize);

Sentencias if, if-else, if else-if else

Las sentencias del tipo if-else deberían tener la siguiente forma:

if ( condition) {
statements;
}
if ( condition) {
statements;
} else {
statements;
}
if ( condition) {
statements;
} else if ( condition) {
statements;
} else {
statements;
}
Nota:
Las sentencias if siempre usan corchetes. Debemos evitar el siguiente error:

if ( condition) //AVOID! THIS OMITS THE BRACES {}!

statement;

Sentencias for
Una sentencia for debería tener la siguiente forma:

for ( initialization; condition; update) {

statements;
}
Una sentencia for vacía (una en la que todo el trabajo se hace en las claúsulas de inicialización,
condición y actualización) debería tener la siguiente forma:

for ( initialization; condition; update);

Cuando usamos el operador coma en las claúsulas de inicialización o actualización de una sentencia
for, debemos evitar la complejidad de usar más de tres variables. Si es necesario, debemos usar
sentencias separadas antes del bucle for (para la claúsula de inicialización) o al final del bucle (para
la claúsula de actualziación).

Sentencias while
Una sentencia while debería tener la siguiente forma:

while ( condition) {
statements;
}
Una sentencia while vacía debería tener la siguiente orma:

while ( condition );

Sentencias do-while
Una sentencia do-while debería tener la siguiente forma:

do {
statements;
} while ( condition);

Sentencias switch
Una sentencia switch debería tener la siguiente forma:
switch ( condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}

Cada vez que un case cae (no incluye una sentencia break), debemos añadir un comentario donde
normalmente iría la sentencia break. Esto se ve en el ejemplo de código anterior con el comentario
/* falls through */.

Toda sentencia switch debería incluir un valor default. El break en el case por defecto es
redundante, pero evita un erro de caída si añadimos después otro case.

Sentencias try-catch
Una sentencia try-catch debería tener la siguiente forma:

try {
statements;
} catch (ExceptionClass e) {
statements;
}
Una sentencia try-catch también podría ir seguida de un cloque finally, que se ejecuta sin importar
si se ha completado con éxito o no el bloque try.

try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}

Líneas en Blanco
Las líneas en blanco mejoran la lectura separando secciones de código que están relacionadas
lógicamente.

Siempre se deberían usar dos líneas en blando en las siguientes circunstancias:

Siempre se debería usar una línea en blanco en las siguientes circunstancias:

Entre métodos
Entre las variables locales de un método y su primera sentencia
Antes de un bloque de comentarios o un comentario simple (ver la lección Comentarios
Entre secciones lógicas dentro de un método para mejorar su lectura

Espacios en Blanco
Los espacios en blanco deberían usarse en las siguientes circunstancias:

Una palabra clave seguida por un paréntesis deberían estar separados por un espacio en blanco:
while (true) {
...
}
Observa que no se debería usar un espacio en blanco entre un nombre de método y su paréntesis de
apertura. Esto nos ayuda a distinguir las palabras clave de las llamadas a métodos.

Después de las comas en una lísta de argumentos debe aparecer un espacio en blanco.
Todos los operadores binarios excpeto "." deberian estar separados de sus operandos por espacios.
Los espacios en blanco nuca deben separar los operadores uniarios como incremento (“++”), y
decremento (“--”) de sus operadores. Por ejemplo:
a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
n++;
}
prints("size is " + foo + "\n");
Las expresiones de una sentencia deberían estár separadas por espacios. Por ejemplo:
for (expr1; expr2; expr3)
Los forzados deberían ir seguidos por un espacio en blanco, por ejemplo:
myMethod((byte) aNum, (Object) x);
myMethod((int) (cp + 5), ((int) (i + 3)) + 1);.

Convenciones para Nombres

Las convenciones de nombrado hacen los programas más entendibles haciéndolos más fáciles de
leer. También pueden proporcionar información sobre la función del identificador, por ejemplo, si
es una constante, un paquete o una clase, lo que puede ayudarnos a entender el código.

Paquetes
Los prefijos de un nombre de paquete único siempre se escribien en letras ASCII minúsculas y
deberían ser uno de los nombres de dominos de alto nivel, actualmente com, edu, gov, mil, net, org,
o uno de los codigos de dos letras que identifican los paísies como especifica el estándard ISO
3166, 1981.
Los siguientes componentes del nombre de paquete varían de acuerdo a las convenciones de
nombrado internas de una organización. Dichas convenciones podrían especificar que ciertos
nombres de componentes directorio serían división, departamento, proyecto, máquina, o nombres
de login.
com.sun.eng

com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese

Clases
Los nombres de clases deben ser mezclas de mayúsculas y minúsculas, con la primera letra de cada
palabra interna en mayúsculas. Debemos intentar mantener los nombres de clases simples y
descriptivos. Debemos usar palabras completas y evitar acrónimos y abreviaturas (a menos que la
abreviatura se use muy ampliamente como URL o HTML). class Raster;
class ImageSprite;

Interfaces
Los nombres de interfaces se tratan igual que los nombres de clases interface RasterDelegate;
interface Storing;

Métodos
Los métodos deberían ser verbos, en mayúsculas y minúsculas con la primera letra del nombre en
minúsculas, y con la primera letra de cada palabra interna en mayúsculas. run();
runFast();
getBackground();

Variables
Las variables, tanto de ejemplar, de clase, como las constantes de clase se escriben en mayúsculas y
minusculas y con la primera letra del nombre en minúsculas, y con la primera letra de cada palabra
interna en mayúsculas. Los nombres de variables no deben empezar con los caracteres subrayado
"_" o dollar "$", incluso aunque estén permtidos.
Los nombres de variables deberían ser cortos y llenos de significado. La elección de una variable
debería ser mnemónica-es decir, diseñada para indicar al observador casual su utilización. Se deben
evitar los nombres de variable de un sólo caracter, excepto para variables temporales. Algunos
nombres comunes de este tipo de variables son: i, j, k, m, y n para enteros.
int i;
char c;
float myWidth;

Constantes
Los nombres de variables constantes de clases y las constantes ANSI deberían escribirse todo en
mayúsculas con las palabras separadas por subrayados (“_”). (Se deberían evitar las constantes
ANSI para facilitar la depuración.) static final int MIN_WIDTH = 4;
static final int MAX_WIDTH = 999;
static final int GET_THE_CPU = 1;

Normas de Programación

Proporcionar Acceso a Variables de Instancia y de Clase

No debemos hacer públicas ninguna variable de ejemplar o de clase sin una buena razón.
Frecuentemente las variables de instancia no necesitan configurarse explícitamente - porque
normalmente esto sucede como un efecto lateral de llamadas a métodos.

Un ejemplo de variables de instancia públicas apropiadas es el cadso donde la clase esencialmente

es una estructura de datos, sin comportamiento. En otras palabras, si tuvieramos una estructura en
lugar de una clase (si Java soportara estructuras), entonces seriá apropiado hacer públicas las
variables de instancia .

Referenciar Variables de Clase y Métodos

Debemos evitar usar un objeto para acceder a variables de ejemplar (estáticas) o métodos. En su
lugar debemos usar la clase. Por ejemplo:

classMethod(); //OK
AClass.classMethod(); //OK
anObject.classMethod(); //AVOID!

Constantes
Las constantes numéricas (literales) no deberían codificarse directamente, excepto -1, 0, y 1, que
pueden aparecer en un bucle for como valores de contador.

Asignaciones de Variables
Debemos evitar asignar varias variables al mismo valor en una sóla sentencia. Es díficil de leer, por
ejemplo:

fooBar.fChar = barFoo.lchar = 'c'; // AVOID!

No debemos usar el operador de asignación en lugares donde pueda ser fácilmente confundible con
el operador de igualdad, por ejemplo:

if (c++ = d++) { // AVOID! (Java disallows)

...
}
Debería escribirse como:

if ((c++ = d++) != 0) {
...
}
No debemos usar asignaciones embebidas en un intento de mejorar el rendimiento de ejecución. Ese
es el trabajo del compilador. Por ejemplo:

d = (a = b + c) + r; // AVOID!
Debería escribirse como:

a = b + c;
d = a + r;
Paréntesis
Generalmente es una buena idea usar paréntesis para liberar expresiones que incluyen mézclas de
operadores para evitar problemas de precedencia de operadores. Incluso si la precedencia del
operador parece clara para nosotros podría no ser así para otros -- no deberíamos asumir que otros
programadores conecen la precedencia tan bién como nosotros.

if (a == b && c == d) // AVOID!
if ((a == b) && (c == d)) // USE

Valores de Retorno
Debemos intentar hacer que la estructura de nuestro programa corresponda con nuesta intención.
Por ejemplo:

if ( booleanExpression) {
return true;
} else {
return false;
}
debería escribirse como:

return booleanExpression;
De forma similar,

if (condition) {
return x;
}
return y;
debería escribirse como:

return (condition ? x : y);

Expresiones antes del ‘?’ en el Operador Condicional

Si una expresión que contiene un operador binario aparece antes del '?' en el operador terciario ?:,
debería ponerse entre paréntesis, por ejemplo:

(x >= 0) ? x : -x;
Comentarios Especiales
Debemos usar XXX en un comentario para marcar algo que es fraudulenteo pero funciona; y
FIXME para marcar algo que es fraudulento y no funciona.

Ejemplo de Código Java

/* @(#)Blah.java 1.82 99/03/18

*
* Copyright (c) 1994-1999 Sun Microsystems, Inc.
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All Rights Reserved.
*
* This software is the confidential and proprietary information of Sun
* Microsystems, Inc. ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Sun.
*/

package java.blah;

import java.blah.blahdy.BlahBlah;

/**
* Class description goes here.
*
* @version 1.82 18 Mar 1999
* @author Firstname Lastname
*/
public class Blah extends SomeClass {
/* A class implementation comment can go here. */

/** classVar1 documentation comment */

public static int classVar1;

/**
* classVar2 documentation comment that happens to be
* more than one line long
*/
private static Object classVar2;

/** instanceVar1 documentation comment */

public Object instanceVar1;

/** instanceVar2 documentation comment */

protected int instanceVar2;

/** instanceVar3 documentation comment */

private Object[] instanceVar3;

/**
* ... constructor Blah documentation comment...
*/
public Blah() {
// ...implementation goes here...
}

/**
* ... method doSomething documentation comment...
*/
public void doSomething() {
// ...implementation goes here...
}
 /**
* ...method doSomethingElse documentation comment...
* @param someParam description
*/
public void doSomethingElse(Object someParam) {
// ...implementation goes here...
}
}