Paquetes (packages)

Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 31 de enero, 2007

Introduccin
Las clases en Java se agrupan por familias que se denominan paquetes (packages). Todas las clases pertenecen a un paquete. Por ejemplo, la clase String pertenece al paquete java.lang y se dice que el nombre completo de String es
java.lang.String

A la hora de referirnos a una clase, por ejemplo para crear un objeto de dicha clase, podemos poner el nombre completo
java.lang.String nombreAlumno= "Jorge Garca";

lo que puede ser tedioso y, para aliviar la redaccin, Java permite referirnos directamente a las clases del paquete java.lang:
String nombreAlumno= "Jorge Garca";

Otros paquetes lo tienen un poco ms difcil. As, la interface List<E> y la clase ArrayList<E> del paquete java.util requerira la notacin completa:
java.util.List<String> notas= new java.util.ArrayList<String>();

Demasiado texto, verdad? Java permite referirnos a los miembros de un paquete por el sombre sencillo de su clase si previamente lo hemos importado:
import java.util.List; import java.util.ArrayList; ... List<String> notas= new ArrayList<String>();

La importacin puede ser clase a clase como en el ejemplo anterior, o podemos importar todas clases del paquete al tiempo:
import java.util.*; ... List<String> notas= new ArrayList<String>();

Si existieran clases con el mismo nombre en diferentes paquetes, el sistema se quejara de la ambigedad, requiriendo el nombre completo del paquete. Ntese que al final no podemos tener dos clases con igual nombre en el mismo paquete.

A qu paquete pertenecen nuestras clases?

Lo ms sencillo es indicarlo explcitamente:
package paquete.maravilloso;

... class xxx { ... }

que crea la clase paquete.maravilloso.xxx. Si no escribimos package, java asigna la clase a un paquete annimo por defecto. Para pequeos experimentos, basta; pero para convivir con otros programadores es muy recomendable asignar las clases siempre a algn paquete.

Utilidad de los paquetes

La primera y ms evidente ventaja del uso de paquetes es que las clases quedan ordenadas y no hay colisin de nombres. Si dos programadores llaman igual a sus clases y luego hay que juntar el cdigo de ambos, basta explicitar a qu paquete nos referimos en cada caso. En las prcticas del laboratorio usamos los paquetes para discernir una prctica de otra:
package lprg.p1; // para la primera prctica, por ejemplo

mbitos de visibilidad
Los paquetes tambin establecen un permetro de visibilidad para las clases y los miembros (variables y mtodos) de las clases cuando no se dice explcitamente si son pblic (para cualquiera, en este o en otro paquete) o private (exclusivamente para esta clase). As, la clase C, la variable v y el mtodo m de la siguiente clase
package lprg.p1; class C { String v= "..."; } void m (...) { ... }

sern accesibles para todas las clases del paquete lprg.p1; pero inaccesibles por clases de otros paquetes. El resultado es una forma muy cmoda de restringir el mbito a "la familia".

Reparacin de programas (debugging)

Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 28 de febrero, 2003

Introduccin
Un programa funciona cuando pasa las pruebas de aceptacin. Si no las pasa, hay que reparar el programa. A veces es evidente lo que hay que arreglar; pero con frecuencia hay que seguir dos fases: 1. identificar lo que va mal (localizar el error) y

2. reparar el cdigo A esta actividad se la conoce en la jerga de la profesin como "debug", expresin que viene de la poca en que los ordenadores ocupaban metros y metros cuadrados y eran utilizados por los bichos (bugs) como alojamiento, creando cortocircuitos que impedan el funcionamiento de los componentes del ordenador. Haba que ir a quitar los bichos para que volviera a funcionar. Ahora ya no es frecuente que hayan bichos y mucho menos que sean la causa de los errores; pero la expresin se conserva por simpata. A la hora de localizar un error es cuando se aprecia un buen diseo arquitectnico del programa. En un programa claro es fcil detectar dnde y cundo se pierde el control. En un programa que es un laberinto, el primero que se pierde es el ingeniero que busca algo que no funciona adecuadamente. De las muchas virtudes de un buen diseo, una principal en programas con objetos es que los objetos respeten el principio de encapsulacin, que es aquel principio que lleva a que las variables sean siempre privadas y slo puedan ser modificadas por los mtodos del objeto que las acoje. En efecto, es muy frecuente que un programa deje de funcionar correctamente a partir del momento en que una variable toma un valor incorrecto (momento a partir del cual el programa desbarra). Si la variable est encapsulada, basta poner un centinela en el mtodo o mtodos que pueden modificarla para rpidamente trazar el momento en que yerra.

Localizacin del error

Probablemente depurar un programa sea siempre un arte y requiera del ingeniero intuicin y fortuna; pero la labor puede ser tan penosa que toda ayuda y apoyo es de agradecer. Dentro de la filosofa de que depurar es un arte, y bajo la (errnea) suposicin de que un error corregido ya no ser error nunca ms, es frecuente encontrar al programador ejecutando el programa paso a paso ("con el debugger") y apuntando en una hoja de papel los valores que van tomando las variables, hasta que se detecta el error y se corrige. Actividad meritoria y que, lamentablemente, hay que repetir con frecuencia pues la experiencia dice que los objetos o tienen muchos errores o tienen muy pocos; es decir, que no hay trmino medio. Esta estadstica se demuestra empricamente cuando se aprecia que hay clases que "siempre estn fallando" y clases "que no fallan nunca", lo que puede deberse a la pericia del programador o, simplemente, a la dificultad propia del problema que resuelven. Sea por una u otra razn, se considera buena prctica incrustar en el propio cdigo los mecanismos de trazado y de chequeos de consistencia que, combinados, nos detectan inmediatamente cundo las variables toman una combinacin de valores explosiva (assert) y qu secuencia ha llevado a la situacin desastrosa (log). Escribir cdigo para dejar trazas (logs) y cdigo para asegurar que las variables toman combinaciones correctas de valores (aserciones) es invertir esfuerzo del presente para afrontar con rpidez problemas del futuro. Como reglas informales, 1. cada vez que se descubra escribiendo una sentencia System.out.println(...) para saber por dnde va un programa, debera considerar introducir una sentencia de traza 2. cada vez que se descubra escribiendo una sentencia System.out.println(...) para saber el valor que toma una variable, debera considerar introducir una asercin

Y, por supuesto, cuando haya localizado (y corregido) el error, NO retire ni las trazas ni las aserciones, sino que deben quedar ah ... por si acaso.

Reparacin de errores
Hay errores que son una tontera y se resuelven con la modificacin local de alguna lnea de cdigo. Pero hay errores que pueden requerir el re-diseo (parcial) del programa. Si el tiempo lo permite, conviene que las reparaciones no conviertan el programa en un montn de harapos, parche sobre parche que (milagrosamente) [parece que] no falla. Si el tiempo lo permite, modifique la arquitectura de clases para que el programa gane en presencia y legibilidad. Se lo agradecer el prximo ingeniero que tenga que reparar el prximo error.

Trazas
Llamamos traza a un informe producido por ek programa cuando ejecuta y que va contando por dnde va y qu valor toman algunas variables que el programador considera relevantes. Una traza es bsicamente algo as:
System.err.println("Estoy aqu"); System.err.println("variable= " + variable);

Conviene que la traza informe de dnde se produce:

System.err.println("paquete.clase.mtodo: Estoy aqu"); System.err.println("paquete.clase.mtodo.variable= " + variable);

Y, para poder dejar las trazas en el programa sin que estn continuamente ensuciando la salida normal, conviene introducir una variable que controle si se produce o no:
static boolean traza= ...; if (traza) System.err.println("paquete.clase.mtodo: Estoy aqu"); if (traza) System.err.println("paquete.clase.mtodo.variable= " + variable);

Como ltimo refinamiento, es til disear un esquema de niveles de detalle, de forma que podamos indicar al programa con qu nivel necesitamos trazas y as slo vemos con el detalle que necesitamos:
static int detalle= ...; if (detalle >= x) System.err.println("paquete.clase.mtodo: Estoy aqu"); if (detalle >= y) System.err.println("paquete.clase.mtodo.variable= " + variable);

Remitimos al lector a un ejemplo sencillo, RaizCuadrada.java que hace uso de las ideas anteriores. Se invita al lector a que modifique el valor de la variable detalle para apreciar el efecto de trazas con diferentes niveles. Por ltimo, indicar al lector que java proporciona un mecanismo de logging ms sofisticado que las sencillas recetas indicadas en este documento.

Aserciones
Llamamos asercin a una condicin lgica (suposicin del programador) que debe ser verdad siempre. En consecuencia, si en algn momento no es cierto lo que suponemos, ms vale detener la ejecucin pues el programa est fallando. Una asercin es bsicamente algo as:
if (! condicion) { System.err.println("No es cierta la condicin"); System.exit(1); }

Conviene que la traza informe de dnde se produce:

if (! condicion) { System.err.println("paquete.clase.metodo: No es cierta la condicin"); System.exit(1); }

Las aserciones deben chequearse SIEMPRE. Salvo que haya serios problemas de tiempo de respuesta del programa, las aserciones no deberan eliminarse nunca. Remitimos al lector a un ejemplo sencillo, RaizCuadrada.java que hace uso de las ideas anteriores. Por ltimo, indicar al lector que java proporciona un mecanismo de assert ms sofisticado que las sencillas recetas indicadas en este documento.

Referencias
Una presentacin de clase. Que localizar errores es un arte queda manifiesto en la cantidad de opiniones contradictorias que se oyen en este mundo. Siempre es interesante leer a Bruce Eckel: Thinking in Java

Documentacin de cdigo
Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 8 de mayo, 2003

1. Introduccin
Documentar el cdigo de un programa es aadir suficiente informacin como para explicar lo que hace, punto por punto, de forma que no slo los ordenadores sepan qu hacer, sino que adems los humanos entiendan qu estn haciendo y por qu. Porque entre lo que tiene que hacer un programa y cmo lo hace hay una distancia impresionante: todas las horas que el programador ha dedicado a pergear una solucin y escribirla en el lenguaje

que corresponda para que el ordenador la ejecute ciegamente. Documentar un programa no es slo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es adems una necesidad que slo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca: 1. todos los programas tienen errores y descubrirlos slo es cuestin de tiempo y de que el programa tenga xito y se utilice frecuentemente 2. todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen xito Por una u otra razn, todo programa que tenga xito ser modificado en el futuro, bien por el programador original, bien por otro programador que le sustituya. Pensando en esta revisin de cdigo es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.

2. Citas
"If your program isn't worth documenting, it probably isn't worth running" J. Nagler. 1995 Coding Style and Good Computing Practices "do not document bad code - rewrite it" R. Caron. 2000 Coding Techniques and Programming Practices "Write the documentation before you write the code." S.W. Ambler. 2000. Writing Robust Java Code

3. Qu hay que documentar?

Hay que aadir explicaciones a todo lo que no es evidente. No hay que repetir lo que se hace, sino explicar por qu se hace. Y eso se traduce en: de qu se encarga una clase? un paquete? qu hace un mtodo? cul es el uso esperado de un mtodo? para qu se usa una variable? cul es el uso esperado de una variable? qu algoritmo estamos usando? de dnde lo hemos sacado? qu limitaciones tiene el algoritmo? ... la implementacin? qu se debera mejorar ... si hubiera tiempo?

4. Tipos de comentarios
En Java disponemos de tres notaciones para introducir comentarios: javadoc Comienzan con los caracteres "/**", se pueden prolongar a lo largo de varias lneas (que

probablemente comiencen con el carcter "*") y terminan con los caracteres "*/". una lnea Comienzan con los caracteres "//" y terminan con la lnea tipo C Comienzan con los caracteres "/*", se pueden prolongar a lo largo de varias lneas (que probablemente comiencen con el carcter "*") y terminan con los caracteres "*/". Cada tipo de comentario se debe adaptar a un propsito: javadoc Para generar documentacin externa (ver comentarios javadoc ms abajo) una lnea Para documentar cdigo que no necesitamos que aparezca en la documentacin externa (que genere javadoc) Este tipo de comentarios se usar incluso cuando el comentario ocupe varias lneas, cada una de las cuales comenzar con "//" tipo C Para eliminar cdigo. Ocurre a menudo que cdigo obsoleto no queremos que desaparezca, sino mantenerlo "por si acaso". Para que no se ejecute, se comenta. (En ingls se suele denominar "comment out") Javadoc, que veremos posteriormente, impone sus propias reglas prcticas.

5. Cundo hay que poner un comentario?

Por obligacin (javadoc): 1. al principio de cada clase 2. al principio de cada mtodo 3. ante cada variable de clase Por conveniencia (una lnea): 4. al principio de fragmento de cdigo no evidente 5. a lo largo de los bucles Y por si acaso (una lnea): 6. siempre que hagamos algo raro 7. siempre que el cdigo no sea evidente Es decir, que los comentarios ms vale que sobren que que falten. Y una nota de cautela, cuando un programa se modifica, los comentarios deben modificarse al tiempo, no sea que los comentarios acaben refirindose a un algoritmo que ya no utilizamos.

6. Javadoc: documentacin de APIs

El paquete de desarrollo Java incluye una herramienta, javadoc, para generar un conjunto de pginas web a partir de los ficheros de cdigo. Esta herramienta toma en consideracin algunos comentarios para generar una documentacin bien presentada de clases y componentes de clases (variables y mtodos). Aunque javadoc no ayuda a la comprensin de los detalles de cdigo, si ayuda a la comprensin de la arquitectura de la solucin, lo que no es poco. Se dice que javadoc se centra en la interfaz (API -

Application Programming Interface) de las clases y paquetes Java. Javadoc realza algunos comentarios, de los que exige una sintaxis especial. Deben comenzar por "/**" y terminar por "*/", incluyendo una descripcin y algunas etiquetas especiales:
/** * Parte descriptiva. * Que puede consistir de varias frases o prrafos. * * @etiqueta texto especfico de la etiqueta */

Estos comentarios especiales deben aparecer justo antes de la dclaracin de una clase, un campo o un mtodo en el mismo cdigo fuente. En las siguientes secciones se detallan las etiquetas (tags) que javadoc sabe interpretar en cada uno de los casos. Como regla general, hay que destacar que la primera frase (el texto hasta el primer punto) recibir un tratamiento detacado, por lo que debe aportar una explicacin concisa y contundente del elemento documentado. Las dems frases entrarn en detalles.

6.1. Documentacin de clases e interfaces

Deben usarse al menos las etiquetas: @author @version La tabla muestra todas las etiquetas posibles y su interpretacin: @author nombre del autor @version identificacin de la versin y fecha @see referencia a otras clases y mtodos

6.2. Documentacin de constructores y mtodos

Deben usarse al menos las etiquetas: @param una por argumento de entrada @return si el mtodo no es void @exception @throws una por tipo de Exception que se puede lanzar (@exception y @throws se pueden usar indistintamente). La tabla muestra todas las etiquetas posibles y su interpretacin: @param nombre del parmetro descripcin de su significado y uso @return descripcin de lo que se devuelve @exception nombre de la excepcin excepciones que pueden lanzarse @throws nombre de la excepcin excepciones que pueden lanzarse @exception y @throws se pueden usar indistintamente.

6.3. Documentacin de campos

Ninguna etiqueta es obligatoria.

6.4. Ejecucin de javadoc

La mayor parte de los entornos de desarrollo incluyen un botn para llamar a javadoc as como opciones de configuracin. No obstante, siempre puede ir al directorio donde instal en JDK y ejecutar javadoc directamente sobre el cdigo fuente Java:
...> {directorio de instalacin}/javadoc *.java

La herramienta javadoc admite miles de opciones. Algunas de las ms usadas aparecen a continuacin:
usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files] -public Show only public classes and members -protected Show protected/public classes and members (default) -package Show package/protected/public classes and members -private Show all classes and members -sourcepath <pathlist> Specify where to find source files -classpath <pathlist> Specify where to find user class files -verbose Output messages about what Javadoc is doing -d <directory> -version -author -docfilessubdirs -splitindex -windowtitle <text> -doctitle <html-code> -header <html-code> -footer <html-code> -bottom <html-code> Destination directory for output files Include @version paragraphs Include @author paragraphs Recursively copy doc-file subdirectories Split index into one file per letter Browser window title for the documenation Include title for the overview page Include header text for each page Include footer text for each page Include bottom text for each page

javadoc -help despliega un catlogo completo de opciones.

7. Referencias
Sun Microsystems, empresa creadora de Java, ha dedicado extenso material a la descripcin de cmo documentar las interfaces de los programas: How to Write Doc Comments for the Javadoc Tool Javadoc se utiliza sistemticamente para documentar el entorno de desarrollo Java.

Estilo de Programacin
Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 8 de mayo, 2003

1. Introduccin
El cdigo de un programa lo leen muchas personas, bien para repararlo, bien para ampliarlo o, simplemente, para evaluarlo. Para estos lectores es fundamental que el programa est bien redactado, con estilo, para que su significado sea claro y difano. An reconociendo que redactar con buen estilo es ms un arte que una ciencia, s existen una serie de reglas bsicas que ayudan a conseguir un texto satisfactorio. En esta nota se incluyen este tipo de reglas. Al igual que cuando aprendemos redaccin literaria, una forma excelente de adquirir un buen estili es leer textos ajenos. Es por ello que recomendamos al alumno la lectura, y an estudio, de programas existentes. Un programa puede escribirse con mejor o peor estilo. En estas notas intentaremos concretar qu se entiende por un programa bien escrito. Que un programa funcione o no es en buena medida independiente de que est bien o mal escrito. No obstante: 1. un programa mal escrito tiene una probabilidad mayor de no funcionar correctamente un buen estilo facilita la correccin 2. es imposible depurar un programa mal escrito 3. es imposible mantener un programa mal escrito Para determinar si un programa est bien escrito estimaremos su legibilidad o capacidad de comunicar lo que hace a otros programadores que tengan que leer el cdigo fuente (para evaluarlo, mantenerlo o repararlo). Por ello escribir un buen programa es tan difcil como escribir un buen libro. Un programador dispone de cuatro mecanismos bsicos para comunicarse con sus lectores: 1. 2. 3. 4. el estilo los comentarios los nombres de las variables, constantes y mtodos los espacios en blanco (el sangrado)

A continuacin se recogen una serie de reglas de buen estilo.

2. Reglas de buen estilo

2.1. Los ficheros de programa deben organizarse de la siguiente forma: 1. documentacin (javadoc) de la clase o interfaz 2. class o interface 3. variables de clase (static) 4. variables de instancia u objeto 5. constructores 6. dems mtodos Un orden sistemtico facilita la bsqueda al lector.

2.1. Sobre las variables

2.1.1. Las variables de clase u objeto jams deberan ser pblicas. Para que nadie pueda alterarlas desde fuera de la clase. 2.1.2. Las variables deben ver reducida su existencia al mnimo tiempo posible; es decir, declararse en el mbito ms reducido que sea posible. Para que nadie se confunda en su uso.

Se preferirn variables de mtodo a variables de objeto. 2.1.3. Las variables deben inicializarse inmediatamente.
int nMuescas= 0;

En previsin de que la variable contenga un valor fuera de control. 2.1.4. Las variables con un mbito muy amplio debern tener nombres largos y muy significativos. Las variables con un mbito muy restringido pueden tener nombres muy cortos.
int i, j; char c; String s;

Las variables que van a retener valores importantes en otras zonas del programa, deben ser retenidas en la memoria del lector, para lo que necesita un nombre suficientemente largo y descriptivo de su contenido. En cambio, las variables de usar y tirar, que solo van a usarse en las prximas lneas, pueden tener cualquier nombre, pues no necesitan ser retenidas por el lector. Es ms, si el lector ve una variable de nombre muy corto, intuitivamente pensar que es una variable sin futuro, que no necesita retener pues tiene la declaracin al lado. 2.1.5. Las variables de iteracin deben tener nombres muy cortos: i, j, k, ...
while (Iterator i= xxx.iterator(); i.hasNext(); ) { ... ... ... } for (int i= 0; i < tabla.length; i++) { ... ... ... }

Porque es habitual en matemticas usar nombres de una letra en iteradores. 2.1.6. Las variables jamas deben tener un doble signitifado.
int valor= 0; // mal: todo son valores

Porque no ayuda a saber para qu sirve una variable. 2.1.7. Jams use la misma variable para retener dos cosas diferentes.
int numero= 0; numero= cuentaOvejas(); numero= cuentaSillas();

Primero, porque no ayuda a entender para qu sirve la variable. Segundo, porque antes o despus el programador la usar con el contenido inadecuado.

2.2. Sobre las expresiones

2.2.1. Evite expresiones (numricas o condiciones lgicas) complejas. Si una expresin se complica, considere la creacin de variables auxiliares o mtodos auxiliares (posiblemente privados). MAL

if ((elementNo < 0) || (elementNo > maxElement)|| elementNo == lastElement) { ... ... ... }

BIEN
boolean isFinished= (elementNo < 0) || (elementNo > maxElement); boolean isRepeatedEntry= elementNo == lastElement; if (isFinished || isRepeatedEntry) { ... ... ... }

Para que sea legible e inteligible. 2.2.2. En una construccin condicional, ponga el caso normal en la parte if y el caso excepcional en la parte else
boolean isError = readFile (fileName); if (!isError) { ... ... ... } else { ... ... ... }

Para que sea legible e inteligible. 2.2.3. Evite comparar con TRUE o FALSE para tomar decisiones. MAL
variable= expresion == true; variable= expresion == false; if (condicion == true) ... if (condicion == false) ... while (condicion == true) ... while (condicion == false) ... for (inicio; condicion == true; siguiente) ... for (inicio; condicion == false; siguiente) ... return condicion == true; return condicion == false;

BIEN
variable= expresion; variable= ! expresion; if (condicion) ... if (! condicion) ... while (condicion) ... while (! condicion) ... for (inicio; condicion; siguiente) ... for (inicio; ! condicion; siguiente) ... return condicion; return ! condicion;

Para que sea legible e inteligible.

2.3. Sobre las estructuras de programa

2.3.1. No use las construcciones break o continue, salvo que sea estrictamente necesario. Para que los bucles sean legibles, sin sorpresas. 2.3.2. En un mtodo que tiene que devolver un resultado dependiendo de varias condiciones; no acumule el resultado: devulvalo en cuanto lo sepa. Se puede lanzar una excepcin o retornar un valor.
int salario (Empleado empleado) throws Exception { if (empleado == null) throw new Exception("empleado null"); int base= salarioBase[empleado.cargo()]; if (empleado.despedido()) return 0; if (empleado.deBaja()) return base*0.8; if (empleado.plusProductividad()) return base*1.1; return base; }

Buscamos leer lo menos necesario para tomar una decisin. 2.3.3. Un bucle no debe ocupar ms de una pantalla (unas 20 lneas de cdigo) desde su inicio hasta su final, incluyendo lneas preliminares para inicializar variables. Considere la oportunidad de "aplanar" el cdigo introduciendo mtodos auxiliares con nombre propio. Para poder leerlos en pantalla. 2.3.4. Evite el anidamiento excesivo de estructuras for, while, if, switch, Si tiene ms de tres (3) estructuras anidadas, considere la oportunidad de "aplanar" el cdigo o de introducir mtodos auxiliares con nombre propio. MAL
String url= null; if (propertyList != null) { for (int i= 0; i < propertyList.size(); i++) { Properties prop= (Properties)propertyList.elementAt(i); if (prop != null) { if (prop.containsKey("url")) { url= prop.getProperty("url"); break; } } } }

BIEN
String url= getProperty(propertyList, "url"); ... ... ... private String getUrl (List propertyList, String key) { if (propertyList == null)

return null; for (int i= 0; i < propertyList.size(); i++) { String value= getProperty((Properties)propertyList.elementAt(i), key); if (value != null) return value; } return null; } private String getProperty (Properties prop, String key) { if (prop == null) return null; return (String)prop.getProperty(key); }

Para que el programa no se convierta en un laberinto.

3. Referencias
Style Guide Objects First with Java (BlueJ) Java Programming Style Guidelines Geotechnical Software Services Coding Standards for Java AmbySoft Inc.

Nomenclatura
Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 8 de mayo, 2003

1. Introduccin
Los nombres de clases, variables y mtodos son un mecanismo bsico para transmitir al lector lo que piensa en programador. En principio, cualquier convenio sera bueno, con el nico requisito de que se siguiere sistemticamente. A continuacin se describe el convenio ms habitual en la comunidad de programadores Java.

2. Reglas de nomenclatura
REGLA GENERAL: cuando un nombre conste de varias palabras, se escribirn una tras otra, sin solucin de continuidad, comenzando cada palabra por mayscula.
VariableDeTresPalabras NumeroDeTelefonosEnLaOficina

Las excepciones a esta regla general se sealan en cada caso.

2.1. Los nombres de los paquetes deben usar solo minsculas.

package lprg.p7;

2.2. Los nombres para las clases deben ser sustantivos. Se sigue la REGLA GENERAL.
ColaLlamadas, Estancia, ListaDeNombres

2.3. Los nombres de las variables siguen la REGLA GENERAL; pero la primera letra ser minscula.
int numeroDeCarneros;

2.4. Las constantes ("variables" final) se escribirn ntegramente con maysculas. Si constan de varias palabras, se separarn estas por "_".
static final int COLOR_ROJO= 0xFF0000;

2.5. Los nombres de los mtodos deben ser verbos. Se sigue la REGLA GENERAL; pero la primera letra ser minscula.
String getNombre (); void setNombre(String string);

2.6. Si una palabra es un acrnico, se sigue la REGLA GENERAL de escribir solo el primer carcter con mayscula (con las salvedades antes apuntadas).
class Dni dniDelSujetoPasivo getUrl()

3. Referencias
Code Conventions for the Java Programming Language Sun Microsystems Inc.

Sangrado
Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 8 de mayo, 2003

1. Introduccin
El sangrado (cmbios de lnea y espacio en blanco al principio) es un mecanismo bsico para transmitir al lector lo que piensa el programador. En principio, cualquier convenio sera bueno, con el nico requisito de que se siguiere

sistemticamente. A continuacin se describe el convenio ms habitual en la comunidad de programadores Java.

2. Longitud de las lneas

2.1. No escriba lneas con ms de 70 caracteres. Si una sentencia requiere ms del lmite, considerr partirla en varias lneas, dejando clato en todas ellas (menos la ltima) que se sigue a continuacin.
String mensaje= "Este es un mensaje un poco largo que, " + "claramente, requiere de ms de una lnea " + "para atenerse a la regla."; int acumulado= capitulo[1] + capitulo[3] + capitulo[5] + capitulo[7] + capitulo[11]; funcion(argumento1, argumento2, argumento3, argumento4, argumento5); for (int indice= 0; indice < tablaDeRutasDeAcceso.length; indice+= 2) { ... ... ... }

3. Reglas de sangrado
3.1. Utilice dos espacios en blanco como medida bsica de sangrado. Evite el uso de caracteres de tabulacin (TAB).
int maximo= tabla[0]; for (int i= 0; i < tabla.length; i++) { if (tabla[i] > maximo) maximo= tabla[i]; }

Para que el cdigo no se arrastre por la derecha. 3.2. Para sangrar clases e interfaces se usar el patrn del ejemplo.
class UnaClase extends OtraClase implements UnaInterfase, OtraInterfase { ... ... ... ... ... ... }

3.3. Para sangrar mtodos se usar el patrn del ejemplo.

public void unMetodo () throws UnaExcepcion { ... ... ... ... ... ... }

3.4. Para sangrar estructuras IF-THEN-ELSE se usar el patrn del ejemplo.

if (condicion) { ... ... ... if (condicion) { ... ... ... if (condicion) { ... ... ...

} else { ... ... ... }

} else if (condicion) { ... ... ... } else { ... ... ... }

3.5. Para sangrar estructuras SWITCH se usar el patrn del ejemplo.

switch (condicion) { case A: ... ... ... break; case B: ... ... ... return zzz; default: ... ... ... }

3.6. Para sangrar bloques while se usar el patrn del ejemplo.

while (quedaPorHacer()) { ... ... ... ... ... ... } do { ... ... ... ... ... ... } while (masQueHacer());

3.7. Para sangrar bloques for se usar el patrn del ejemplo.

for (inicializacion(); condicion(); siguiente()) { ... ... ... ... ... ... }

3.8. Una iteracin sin sentencias de cuerpo ser como en el ejemplo.

for (inicializacion(); condicion(); siguiente()) ;

3.9. Para sangrar estructuras TRY se usar el patrn del ejemplo.

try { ... ... ... } catch (Exception e) { ... ... ... } try { ... ... ... } catch (Exception e) { ... ... ... } finally { ... ... ... } try { ... ... ... } finally { ... ... ... }

3.10. En estructuras de bloque con solo una sentencia, se pueden obviar las llaves.
if (condicion) hazAlgo(); while (condicion) hazAlgo(); for (inicializacion; condicion, actualizacion) hazAlgo();

4. Referencias
Java Programming Style Guidelines Geotechnical Software Services Code Conventions for the Java Programming Language Sun Microsystems Inc.

Log: trazas de ejecucin

Jos A. Maas <jmanas@dit.upm.es> Dept. de Ingeniera de Sistemas Telemticos Universidad Politcnica de Madrid 5 de febrero, 2006

1. Introduccin
Los programas no triviales hacen muchas cosas entre que toman los datos de entrada y generan la salida. A veces interesa tener un registro de lo que va sucediendo, con ms o menos detalle. El nivel de detalle de las trazas de ejecucin interesa que sea ajustable segn las circunstancias: dinmicamente.

1.1. Depuracin
Un caso tpico en el que nos interesa que el programa "se explique" paso por paso es cuando estamos depurando: el programa no funciona y necesitamos descubrir dnde falla para repararlo. Las trazas sern de poco detalle cuando empezamos a buscar; pero iremos aumentando el detalle segn vayamos acorralando el error. No es ninguna novedad que los programadores "trufen" el cdigo de sentencias System.err.println para dejar traza de por dnde vamos pasando y en valor que van tomando las variables. Lo malo de esta aproximacin es que las sentencias de escritura hay que anularlas cuando el sistema se pone en produccin, bien comentndolas, bien eliminndolas, bien armando algn mecanismo de control dinmico del nivel de detalle deseado (as, nivel cero significa que no hay traza alguna, lo que es tpico de produccin). Java incluye un paquete que permite automatizar la tarea de activar y desactivar trazas con diferente nivel de detalle.

2. package log.Logger
Se trata de un paquete preparado para realizar las prcticas de la asignatura. Est inspirado en el paquete java.util.logging de la librera de Java (que se describe al final); pero adaptado a la asignatura. Es necesario incluir el paquete: import log.Logger; Para trazar necesitamos un logger: Logger LOGGER= Logger.getLogger("NOMBRE")

2.1. El nombre del logger

El programador puede bautizar su logger como le apetezca, si bien lo usual es usar el nombre del paquete y la clase para que la estructura de las trazas sea paralela a la estructura de paquetes, clases y mtodos: private static final Logger LOGGER= Logger.getLogger("paquete.clase") Decidir exactamente el nivel de granularidad depende de cada caso. Podemos empezar con un logger por paquete: private static final Logger LOGGER= Logger.getLogger("paquete") Si el paquete es grande (muchas clases) puede ser interesante tener un logger para cada clase o para algunas clases: private static final Logger LOGGER= Logger.getLogger("paquete.clase") Si una clase es muy grande (muchos mtodos) puede ser interesante tener in logger para cada mtodo o para algunos mtodos: private static final Logger LOGGER= Logger.getLogger("paquete.clase.metodo") En los ejemplos de estos apuntes usaremos un logger por clase. Los nombres forman una jerarqua o "rbol genealgico" que nos permitir fijar el nivel de detalle de traza de familias enteras, pues el nivel que fijemos para un logger ser el que usen todos sus "descendientes", salvo indicacin expresa. As podremos dar reglas para todos los paquetes, reglas que refinaremos en algunos paquetes, podremos refinar ms por clases e incluso por mtodos. Segn haga falta.

2.2. Nivel de detalle

java.util.logging define algunos niveles tpicos que, sin ser obligatorios, permiten clasificar las trazas en familias: OFF No se genera traza alguna. SEVERE Se usa para trazar errores catastrficos, que son aquellos de los que no hay recuperacin posible, provocando la terminacin del programa. La traza recoge el fallo causante de la detencin. WARNING Se usa para trazar errores peligrosos, para los que hay previsto un mecanismo de supervivencia. INFO Trazas normales: para ir viendo lo que pasa. CONFIG Se usan tpicamente al arrancar un programa para trazar la configuracin inicial, que frecuentemente se lee de alguna parte. FINE Informacin de detalle, tpicamente til para localizar errores (depuracin). FINER Informacin de ms detalle, tpicamente til para localizar errores (depuracin). FINEST Informacin de mximo detalle, tpicamente til para localizar errores (depuracin). ALL Se traza todo, a cualquier nivel. Los siguientes ejemplos de uso deberan ser obvios:
LOGGER.log(Logger.WARNING, "mensaje"); LOGGER.severe("mensaje"); LOGGER.warning("mensaje"); LOGGER.info("mensaje"); LOGGER.config("mensaje");

LOGGER.fine("mensaje"); LOGGER.finer("mensaje"); LOGGER.finest("mensaje");

2.3. Excepciones
El lanzamiento de excepciones se puede trazar de diferentes maneras. La ms sencilla consiste en asociar el texto de la excepcin a la traza: LOGGER.warning("mensaje " + e); Tambin se puede pasar como tercer argumento a log: LOGGER.log(Logger.WARNING, "mensaje ", e);

3. Configuracin
El programador describir en un fichero de propiedades los detalles de qu traza desea. Se usa siempre el fichero $HOME/logger.java El directorio $HOME depende del sistema operativo en el que trabajemos; pero si el paquete no encuentra el fichero, indica por medio de un mensaje en consola qu es lo que estaba buscando, de forma que podamos llevar el fichero a su sitio.
$ java Diccionario no se encuentra: C:\Documents and Settings\pepe\java.logger

Y cuando lee el fichero, indica qu es lo que est leyendo:

$ java Diccionario java.logger <- C:\Documents and Settings\pepe\java.logger

El fichero java.logger indica varias cosas. .level= ALL mnimo nivel que aparecer por consola o fichero .console.level= ALL mnimo nivel que aparecer por consola (System.err) .file.level= SEVERE mnimo nivel que aparecer en fichero .file.name= J$.log nombre del fichero en el que se escribe la traza (se llamar "J" algo ".log" en el mismo directorio en el que est java.logger) Diccionario= INFO el logger de nombre "Diccionario" trazar a nivel INFO y superiores paquete= nivel los logger de nombre "paquete..." trazarn al nivel indicado y superiores paquete.clase= nivel los logger de nombre "paquete.clase..." trazarn al nivel indicado y superiores paquete.clase.metodo= nivel los logger de nombre "paquete.clase.metodo..." trazarn al nivel indicado y superiores Si un Logger tiene por nombre una serie de palabras separadas por puntos a.b.c.d se buscar sucesivamente alguna entrada en java.logger que diga

1. 2. 3. 4. 5.

a.b.c.d= NIVEL a.b.c= NIVEL a.b= NIVEL a= NIVEL .level= NIVEL

aplicndose el NIVEL de la primera que encuentre. Recuerde que los nombres forman un "rbol genealgico".

4. Ejemplo
Diccionario.java es un programa Java que busca una palabra en un diccionario, estando el programa preparado para trazar su comportamiento en diferentes niveles de detalle. Para probar, debe organizar la jerarqua de directorios paralela a la jerarqua de paquetes. Algo as
C:\java\lprg\2006-01-31\Diccionario.java C:\java\lprg\2006-01-31\log\Logger.java

Para ejecutar el programa ejemplo puede interesarle usar este diccionario inicial de palabras. Se adjunta el resultado de ejecutar con diferente nivel de traza: Diccionario= OFF Diccionario= SEVERE Diccionario= WARNING Diccionario= INFO Diccionario= CONFIG Diccionario= FINE Diccionario= ALL

2. java.util.logging
java.util.logging es un paquete Java para automatizar el trazado de programas. Es parte de la distribucin estndar de Java y no hay que hacer ninguna instalacin especial para usarlo. El paquete java.util.logging es similar a log.Logger pero permite hacer muchas ms cosas que las que se describen en esta nota. Para una referencia completa, se remite al lector a Java Logging Overview Thinking in Java, el libro de Bruce Eckel, incluye un captulo dedicado a las trazas con extenso detalle.