Académique Documents
Professionnel Documents
Culture Documents
El presente documento trata sobre las convenciones en la codificacin de programas en Java, estas
convenciones son proporcionadas por Sun, en su original en ingls.
He aqu el contenido
1. Introduccin
1.1 Porqu tenemos convenciones de cdigo
1.2 Reconocimientos
2. Nombres de archivos
2.1 Sufijos de archivo
2.3 Nombres de archivo comunes
3. Organizacin de archivos
3.1 Archivos fuente en Java
3.1.1 Comentarios iniciales
3.1.2 Sentencias de declaracin de paquete e importacin
3.1.3 Declaraciones de interfaz
4. Tabulaciones y sangras
4.1 Longitud de lnea
4.2 Ajuste de lneas
5. Comentarios
5.1 Formatos de implementacin de comentarios
5.1.1 Comentarios de bloque
5.1.2 Comentarios de lnea simple
5.1.3 Comentarios de rastreo
5.1.4 Comentarios de fin de lnea
5.2 Comentarios de documentacin
6. Declaraciones
6.1 Nmero por lnea
6.2 Inicializacin
6.3 Ubicacin
6.4 Declaraciones de clase e interfaz
7. Sentencias
7.1 Sentencias simples
7.2 Sentencias compuestas
7.3 Sentencias return
7.4 Sentencias if, if-else, if-else-if-else
7.5 Sentencias for
7.6 Sentencias while
7.7 Sentencias do-while
7.8 Sentencias switch
7.9 Sentencias try-catch
8. Espacios en blanco
8.1 Lneas en blanco
8.2 Espacios en blanco
9. Convenciones sobre los nombres
10. Prcticas de programacin
10.1 Proveer acceso a variables de instancia y clase
10.2 Referenciar variables de clase y mtodos
10.3 Constantes
10.4 Asignacin de variables
10.5 Prcticas diversas
10.5.1 Parntesis
10.5.2 Retorno de valores
10.5.3 Expresiones antes del operador condicional "?"
10.5.4 Comentarios especiales
11. Ejemplo de cdigo
11.1 Ejemplo de cdigo fuente Java
1 Introduccin
1.1 Porqu tenemos Convenciones de Cdigo?
Las convenciones de cdigo son importantes para los programadores por un nmero de razones:
Para trabajar con las convenciones de cdigo, todas las personas que escriben el software deben adaptarse a las
convenciones de cdigo. Todas.
1.2 Reconocimientos
Este documento refleja los estndares de Java presentados en la Especificacin de Lenguaje Java de Sun Microsystems,
Inc. Las mayores contribuciones son de Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath y
Scott Hommel.
2 Nombres de archivos
Tipo de Archivo
Sufijo
.java
Java bytecode
.class
Nombre de
Archivo
Uso
GNUMakefile
README
Notas
Variables de instancia
Constructores
Mtodos
4. Tabulaciones y sangras
Se deben usar cuatro espacios como unidad de sangrado. La elaboracin exacta del sangrado (espacio vs. tabulaciones)
no se especifica. Las tabulaciones deben se exactamente cada 8 espacios (no 8).
Los siguientes son dos ejemplo de sangrado en las declaraciones de mtodos. La primera es el tipo convencional. La
segunda alternar la segunda y la tercera lneas ms a la derecha que si se usara sangrado convencional, en lugar de eso
se sangra slo 8 espacios
//SANGRADO CONVENCIONAL
algunMetodo(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
//SANGRADO DE 8 ESPACIOS DEJANDO DE LADO SANGRADOS MUY PROFUNDOS
private static synchronized nombreLargoDeMetodo(int unArg,
Object otroArg, String todaviaOtroArg,
Object otroMas) {
...
}
El ajuste de lnea para sentencias if deben usar generalmente la regla de 8 espacios, puesto que el sangrado
convencional (de 4 espacios) hace difcil ver el cuerpo del cdigo. Por ejemplo:
//NO USE ESTE SANGRADO
if ((condicion1 && condicion2)
|| (condicion3 && condicion4)
||!(condicion5 && condicion6)) { //MAL AJUSTADO
hacerCualquierCosa(); //HACE ESTA LNEA FACIL DE PERDER
}
//USE ESTE SANGRADO EN SU LUGAR
if ((condicion1 && condicion2)
|| (condicion3 && condicion4)
||!(condicion5 && condicion6)) {
hacerCualquierCosa();
}
//O USE ESTE
if ((condicion1 && condicion2) || (condicion3 && condicion4)
||!(condicion5 && condicion6)) {
hacerCualquierCosa();
}
Aqu hay tres formas permisibles de formatear expresiones ternarias.
alfa = (unaExpresionBooleanaGrande) ? beta : gama;
alfa = (unaExpresionBooleanaGrande) ? beta
: gama;
alfa = (unaExpresionBooleanaGrande)
? beta
: gama;
5. Comentarios
Los programas Java pueden tener dos formas de comentarios: comentarios de implementacin y comentarios de
documentacin. Los comentarios de implementacin son aquellos encontrados en C++, los cules stn delimitados por
/*...*/, y //. Los comentarios de documentacin (conocidos como "comentarios doc") son slo Java, y estn
delimitados por /**...*/. Los comentarios doc pueden extraerse a archivos HTML usando la herramienta javadoc.
Los comentarios de implementacin son formas para comentar cdigo o para comentar una implementacin particular.
Los comentarios doc sirven para describir la especificacin del cdigo, desde una perspectiva de aplicacin libre para que
lean los desarrolladores que no necesariamente tienen el cdigo fuente a la mano.
Los comentarios deben usarse para conseguir resmenes del cdigo y proveer informacin adicional que es difcil de
obtener del cdigo en si. Los comentarios deben contener slo la informacin que sea relevante para la lectura y
entendimiento del programa. Por ejemplo, la informacin acerca de como se arma el paquete correspondiente o en que
directorio est, no deben estar incluidos como comentarios.
La discusin sobre las decisiones del diseo, si son triviales u obvias, es buena, pero hay que evitar la informacin
duplicada que este presente en el cdigo (y desaparecerla). Los comentarios redundantes tambin se se vuelven
obsoletos con mucha facilidad. En general, hay que evitar cualquier comentario que probablemente est de ms a medida
que el cdigo evolucione.
Nota: La frecuencia de comentarios algunas veces refleja una calidad pobre de cdigo. Cuando se sienta obligado a
agregar un comentario, considere reescribir el cdigo para hacerlo ms claro.
Los Comentarios no deben estar encerrados en grandes cajas de asteriscos u otros caracteres
Los comentarios nunca deben contener caracteres especiales como alimentacin de pgina o retroceso.
...
}
Si necesitamos dar informacin acerca de una clase, interface, variable, o mtodo que no es apropiada para ser incluida
en la documentacin, use un comentario de bloque (vea la seccin 5.1.1) o de lnea simple (vea la seccin 5.1.2)
inmediatamente despus de la declaracin. Por ejemplo, los detalles acerca de la implementacin de una clase debe ir en
un comentario de bloque seguido de la sentencia class, no en el comentario doc de la clase.
Los comentarios doc no deben ponerse dentro de un mtodo o en el bloque de definicin de un constructor, porque java
asocia los comentarios de documentacin con la primera declaracin despus del comentario.
6. Declaraciones:
6.1 Nmero por lnea
Se recomienda una declaracin por lnea puesto que de esta forma se pueden hacer comentarios. en otras
palabras
int level; // nivel de identacin
int size; // tamao de la tabla
Se prefiere a:
int level, size;
Nota: los ejemplos citados usan un espacio entre el tipo y el identificador. Otra forma aceptable es usando
tabulaciones, por ejemplo:
int
int
Object
6.2 Inicializacin
Pruebe inicializando variables locales al declararlas. La nica razn para no inicializarl una varaiale al
declararla es que el valor inicial dependa de alguna operacin.
6.3 Ubicacin
Ponga las declaraciones en los bloques de inicio. (Un bloque es cualquier cdigo delimitados por las llaves "{"
y "}") No espere a declarar las variables hasta que tenga que usarlas; esto puede confundir a los programadores
incautos y entorpece la portabilidad de cdigo.
void myMethod() {
int int1 = 0; // bloque inicial del metodo
if(condicion) {
int int2 = 0; // comienzo del bloque "if"
...
}
}
La nica excepcin a esta regla son los ndices de los bucles for:
for (int i = 0; i < maxLoops; i++) { ... }
Evitar las declaraciones locales que solapen las declaraciones en niveles ms altos. Por ejemplo, no declare la
misma variable en un bloque interior
int count;
...
myMethod() {
if (condicion) {
int count; // EVITELO!
...
}
...
}
No espacios entre el nombre del mtodo y los parntesis "(" que inicia la lista de parmetros.
La llave de apertura "{" aparece al final en la misma lnea de la sentencia de declaracin.
La llave de cierre "}" inicia un lnea y se identa al nivel de la declaracin, excepto cuando se trata de una
sentencia nula, entonces el "}" aparece inmediatamente despus del "{".
7. Sentencias
7.1 Sentencias simples
Cada lnea debe contener a lo sumo una sentencia. Ejemplo:
argv++; // Correcto
argc++; // Correcto
argv++; argc--; // EVITELO!
Las llaves se usan encerrando todas las sentencias, an sentencias simples, cuando son parte de una estructura
de control, como un if-else o una sentencia for. Esto hace fcil agregar sentencias sin introducir errores
accidentalmente por olvidar poner las llaves.
una sentencia try-catch tambin puede estar seguida de un finally, el cual se ejecuta independientemente de si el
bloque try se complet o no con xito.
try {
sentencias;
}catch (ClaseExcepcion e) {
sentencias;
} finally {
sentencias;
}
8. Espacios en blanco
8.1 Lneas en blanco
La lneas en blanco mejoran la legibilidad estableciendo secciones de cdigo que estn relacionadas lgicamente.
Dos lneas en blanco deben usarse siempre en las siguientes circunstancias:
Entre mtodos
Entre las variables locales en un mtodo y su primer sentencia.
Antes de un comentario en bloque (vea la seccin 5.1.1) o uno simple (vea la seccin 5.1.2)
Entre secciones lgicas dentro del mtodo para mejorar la legibilidad.
Una palabra clave seguida de un parntesis deben estar separados por un espacio:
while
(true)
{
...
}
Nota: El espacio en blanco no debe usarse entre el nombre de un mtodo y su parntesis de apertura. Esto ayuda
distinguir las llamadas a los mtodos de las palabras clave.
Un espacio en blanco debe aparecer despus de las comas en las listas de argumentos.
Todos los operadores binarios excepto "." deben estar separados de sus operandos por espacios. Los espacios en
blanco nunca deben separar operadores unitarios como el menos unitario, incremento(++) y decremento(--), de
sus operandos:
a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
n++;
}
prints("size is " + foo + "\n");
Las expresiones en una sentencia for deben estar separadas por espacios en blanco.
Tipo de identificador
Reglas de nombre
Ejemplos
Clases
Interfaces
Mtodos
Variables
Constantes
class Raster
interface RasterDelegate
interface Storing
run();
runFast();
getBackground();
int
char
float myWidth;
i;
c;
static
final
MIN_WIDTH
=
int
4;
class ImageSprite
static
final
MAX_WIDTH =
static
final
GET_THE_CPU = 1;
int
999;
int
10.3 Constantes
Las constantes numricas (literales) no deben codificarse directamente, excepto para -1, 0 y 1, las que pueden aparecer
en un bucle for como valores de conteo
d = (a = b + c) + r; // EVITELO!
Debe escribirse como:
a = b + c;
d = a + r;
10.5.1 Parntesis
Es una buena idea usar generosamente los parntesis en expresiones que involucren mezclas de operadores para evitar
problemas de precedencia de operadores. Aun si la precedencia de operadores le parece clara, no significa que tambin
lo sea para otros programadores - no debemos asumir que otros programadores conocen la precedencia tan bien como
nosotros.
if (a == b && c == d) // EVITELO!
if ((a == b) && (c == d)) // USELO
y);
/*
* @(#)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;
/**
* La descripcion de la clase viene aqui
*
* @version 1.82 18 Mar 1999
* @author Firstname Lastname
*/
public class Blah extends SomeClass {
/* Un comentario de implementacion de clase va aqui */
/** comentario de documentacion para classVar1 */
public static int classVar1;
/**
* Comentario de documentacion para classVar2
* que tiene mas de una linea
*/
private static Object classVar2;
/** comentario de documentacion para instanceVar1 */
public Object instanceVar1;