Convenciones de cdigo para el Lenguaje de Programacin Java.

1 - Introduccin Este documento describe una serie de estndares, convenciones y guas para escribir cdigo java slido Estos proveen principios de ingeniera que conducen a cdigo de fcil entendimiento, mantenimiento y mejoramiento. Adems, por siguiente estas normas de codificacin deben aumentar su productivaza como programador Java .La Experiencia muestra que por tomando el tiempo para escribir el cdigo de alta calidad directamente del principio usted tendr un tiempo mucho ms fcil para modificar durante el proceso de desarrollo. Finalmente, despus de un juego comn de cifrar normas, estas conducen a una consistencia mayor, haciendo a los equipos de programadores considerablemente ms productivos.

2 Nombres de archivos

2.1 Sufijo de Archivos Java usa los siguientes sufijos Tipo de Archivo Java source Java bytecode Java Server Face Java Server Face XML Sufijo .java .class .jsp .jspx

3 Organizacin De Archivos Un archivo consiste en secciones que podran estar separadas por lneas en blanco y comentarios opcionales identificando cada seccin. Archivos de ms de 2000 lneas son incmodos y deberan ser evitados.

3.1 Archivos Fuentes Java Cada archivo fuente Java contiene una clase o interface publica. Cuando las clases e interfaces son asociadas con clases pblicas, se puede juntar en el mismo archivo

como una clase publica. La clase pblica puede ser la primera clase o interface en el archivo. Los archivos fuentes de java tienen el siguiente orden. Sentencias de Package e Import. Declaracin de clases e interfases.

3.1.1 Comentarios iniciales Todos los archivos de Fuentes pueden empezar con un comentario c-style que lista el nombre de la clase, informacin de la versin, fecha y mencin de propiedad intelectual: /* * Nombre de la clase * * Informacin de la versin * * Fecha * * Mencin de propiedad */ 3.1.2 Sentencias de Package e Import. La primera lnea sin comentar de un archivo java es la sentencia del package. Despus de esto las sentencias de import continan. Por ejemplo: package com.smcma; import com.smcma.model.Programacion; 3.1.3 Declaracin de Clases e interfaces. La siguiente tabla describe las partes de una declaracin de una clase o interface, en el orden que podra aparecer. Parte de una declaracin Comentario Clase/Interface de Clase/Interface Notas

documentacion (/**...*/) Sentencias de clase o interface Comentario de Implementacin Clase/Interface (/*...*/), si

de

Este

comentario

debe

contener

fuera

informacin que no es apropiada para el

necesario Variables (static) de Clase

comentario documentacin. Primero las variables publicas, luego las protegidas, luego las de nivel de paquete y luego las privadas. Primero publicas, luego protegidas, luego de nivel de paquete y luego privadas.

Variables Instanciadas Constructores

Este Mtodos

mtodo

debe ms que

agrupar por lugar

por o

funcionalidad accesibilidad.

4 - Indentacion Cuatro espacios podran ser usados como la unidad de indentacion.

4.1 Longitud De lnea Evite lneas que excedan los 80 caracteres, ya que ellos no son manejados bien por muchos terminales y herramientas.

4.2 Lneas Envolventes Cuando una expresin no cabe sobre una sola lnea, se partir segn estos principios generales: Partir despus de una coma. Partir antes de un operador. Preferir altos niveles de particin que cortos niveles de particin. Alinear la nueva lnea con el inicio de la expresin en el mismo nivel de la lnea anterior. Ejemplos de particionamiento de llamadas a mtodos. someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3));

Siguiendo estos dos ejemplos de particionamiento de expresiones aritmticas. El primero refiere, a una particin ocurrida fuera de la expression de parntesis, el cual es de alto nivel. longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // PREFERIBLE longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // EVITAR Siguiendo estos dos ejemplos de indentacion en la declaracin de mtodos. El primero es un caso convencional. El segundo cambiaria la segunda y tercera lnea muy a la derecha, en cambio este indenta solo 8 espacios

//CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } //IDENTACION DE 8 ESPACIOS PARA EVITAR MUY PROFUNDAS IDENTACIONES private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... }

Una lnea que contiene sentencias If, generalmente podra usar la regla de los 8 espacios, desde la indentacion convencional, se hace difcil ver el cuerpo Por ejemplo. //DON'T USE THIS INDENTATION if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //MAL FINAL doSomethingAboutIt(); //LINEA FACIL DE FALLAR } //USAR ESTA IDENTACION if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } //O USAR ESTO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) {

doSomethingAboutIt();

Aqu hay tres opciones para formatear expresiones ternarias. alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma;

5 - Comentarios Los Programas en Java tienen dos tipos de comentarios: Comentarios de Implementacin y Documentacin. Los Comentarios de Implementacin son estos que se encuentran en C++, los cuales son definidos por /*...*/, y //. Comentarios de Documentacin (conocidos como comentarios doc) son solamente java y son delimitados por /**...*/. Estos son extrados a archivos HTML usando la herramienta javadoc.

Los comentarios de Implementacin son en la prctica vagos para comentar hacia fuera del cdigo o para comentarios sobre una puesta en prctica. Los comentarios de Documentacin se proponen para describir la especificacin del cdigo, de una perspectiva sin puesta en prctica. Puede ser ledo por los reveladores que no necesariamente podran tener el cdigo original al alcance de la mano.

Los Comentarios pueden ser usados para dar resmenes de cdigo y proveer informacin adicional que no esta fcilmente accesible en el cdigo. Los Comentarios contienen solo informacin que es relevante para leer y entender el programa. Por Ejemplo, informacin acerca de cmo un correspondiente paquete esta construido o en que directorio este reside no debe ser incluido como comentario.

5.1 Formatos de Comentarios de Implementacin Programas pueden tener cuatro estilos de comentarios de implantacin: bloque, lnea-simple, rastreo y final-de-lnea

5.1.1 Comentarios De Bloque Los Comentarios de Bloque son usados para proveer descripcin de archivos, mtodos, estructura de datos y algoritmos. Esos comentarios son usados para iniciar cada archiva y antes de cada mtodo. Ellos pueden ser usados en otros lugares, como dentro de los mtodos. Los Comentarios de Bloque dentro de una funcin o mtodo pueden ser indentados en el mismo nivel del cdigo que ellos describen. Un comentario en bloque podra preceder por una lnea en blanco para ponerlo aparte del resto del cdigo. /* * Aqu son los comentarios en bloque. */ Comentarios en bloque pueden empezar con

/*-, el cual es reconocido por

indent(1) como el inicio de un comentario en bloque que no es reformateado. Ejemplo: /** Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */ 5.1.2 Comentario de Lnea-Simple Los Comentarios cortos pueden aparecer en una lnea simple indentada al nivel del cdigo que sigue. Si un comentario no puede ser escrito en una lnea, este debe seguir el formato de comentario en bloque. Un comentario de lnea-simple pude ser precedido por una lnea en blanco. Aqu un ejemplo de un comentario de lneasimple en un cdigo Java. if (condicion) {

/* Manejar la condicin. */ ... } 5.1.3 Comentarios de Rastreo Comentarios muy cortos pueden aparecer en la misma lnea que el cdigo, pero deberan estar situados bastante lejos de las declaraciones. Si ms de un comentario corto aparece en un segmento de cdigo, estos deben estar al mismo nivel. Aqu un ejemplo de un comentario de rastreo. if (a == 2) { return TRUE; } else { return isPrime(a); } /* special case */ /* works only for odd a */

5.1.4 Comentarios Fin-de-Lnea El // delimitador de comentario puede comentar fuera de un lnea completa o solo de una lnea parcial. Estos pueden ser utilizados en lneas consecutivas; adems, pueden ser usados para comentar mltiples lneas de una seccin de cdigo. 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; //} 5.2 Comentarios de Documentacion Comentarios Doc describen Clases Java, interfaces, constructores, mtodos y campos. Cada comentario Doc es colocado dentro de un delimitador de comentario /**...*/, con un comentario por clase, interface o miembro. Este comentario podra aparecer justo antes de la declaracin.

/** * La Clase Ejemplo provee ... */ public class Ejemplo { ... 6 - Declaraciones 6.1 Numero por Lnea Una declaracin por lnea es recomendada ya que esto anima a comentar. int level; // nivel de indentacion int size; // tamao de la tabla es preferable sobre, int level, size; No poner diferentes tipos sobre la misma linea. Ejemplo: int foo, fooarray[]; //ERRONEO! Tambien se pueden usar tabs entre los tipos y los identificadores. Ejemplo: int level; // indentation level int size; // size of table Object currentEntry; // currently selected table entry 6.2 Inicializacin Inicializar variables locales donde estas son declaradas. La nica razn para no inicializar una variables donde esta declarada es que su valor inicial dependa de alguna ocurrencia computacional.

6.3 Placement Poner declaraciones solo al inicio de bloques. void myMethod() { int int1 = 0; // Empezando un bloque de mtodo if (condition) { int int2 = 0; } // Empezando un bloque if

} La nica excepcin de la regla son los ndices para los bucles, los cuales en java pueden ser declarados en la misma sentencia. for (int i = 0; i < maxLoops; i++) { ... } Evitar declaraciones locales que ocultan declaraciones de alto nivel. Por Ejemplo, no declarar la misma variable en un mismo bloque. int count;

... myMethod() { if (condition) { int count = 0; ... } ... }

// EVITAR

6.4 Declaracin de Clases e Interfaces Cuando codificas interfaces o clases java, debes seguir las siguientes reglas de formato: No espacios entre un nombre de mtodo y el parntesis (. Al abrir llave { este debe aparecer en el fin de la misma lnea que declara al sentencia. Al cerrar llave } este deber aparecer indentado al mismo nivel que la llave de inicio. Cuando la sentencia es nula el } aparece inmediatamente despus del { . class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... } Metodos son separados por lneas en blanco.

7 - Expresiones 7.1 Expresiones Simple Cada lnea puede contener al menos una sentencia. Ejemplo: argv++; // Correcto argc--; // Correcto argv++; argc--; // AVOID! 7.2 Expresiones Compuestas

Sentencias Compuestas son sentencias que contienen listas de sentencias cerradas en llaves {sentencia}. Ejemplos: Las declaraciones incluidas deben estar indentadas en un mayor nivel que las sentencias compuestas. El abrir llaves puede ser en el fin de la lnea que inicia la sentencia compuesta; el cerrar llaves puede iniciar en una lnea y ser indentado al inicio de una sentencia compuesta. Las llaves son usados alrededor de sentencias. Aun si son sentencias simples, cuando ellos son parte de una estructura de control, como un ifelse o for. Esto hace fcil agregar sentencias sin introducir accidentalmente errores u olvidar agregar llaves.

7.3 Expresin de retorno. Una sentencia de retorno con un valor no debera usar parntesis a menos que el valor de retorno sea obvio de alguna forma. Ejemplo: return; return myDisk.size(); return (size ? size : defaultSize); 7.4 Expresiones if, if-else, if else-if else La if-else sentencia debe tener la siguiente forma: if (condition) { expresiones; } if (condition) { expresiones; } else { expresiones; } if (condition) { expresiones; } else if (condition) { expresiones; } else{ expresiones; }

Nota: sentencias if siempre usan llaves. Evitar el siguiente error de forma. if (condition) //EVITAR! ESTO OMITE LAS LLAVES. {}! statement; 7.5 Expresion for Una sentencia for debe tener la siguiente forma: for (initialization; condition; update) { expresiones; } Una sentencia vaca debe tener la siguiente forma: for (initialization; condition; update); Cuando uses el operador coma en la inicializacin o actualizaciones de clusulas en una sentencia for, evitar la complejidad de usar mas de tres variables. Si necesitas, usar sentencias separadas antes del bucle for o en el fin del bucle.

7.6 Expresion while Una declaracin while debe tener la siguiente forma: while (condition) { statements; } Una sentencia vaca debe tener la siguiente forma: while (condition); 7.7 Expresion do-while Una sentencia do-while debe tener la siguiente forma: do { statements; } while (condition); 7.8 Expresion switch Una sentencia switch debe tener la siguiente forma:

switch (condition) { case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; } 7.9 Expresion try-catch Una declaracin try-catch debe tener el siguiente formato: try { statements; } catch (ExceptionClass e) { statements; } Una sentencia try-catch debe seguir de un finally, el cual ejecuta

independientemente si el bloque try ha sido completado satisfactoriamente. try { statements; } catch (ExceptionClass e) { statements; } finally { statements; } 8 Espacio Blanco 8.1 Lneas en Blanco Las Lneas en blanco mejoran la legibilidad al separar secciones de cdigo que son relacionadas lgicamente. Dos lneas en blanco son usadas en las siguientes circunstancias: Entre secciones de un archivo. Entre definiciones de clases e interfaces.

Una lnea en blanco es siempre usada en las siguientes circunstancias:

Entre mtodos Entre variables locales en un mtodo y en la primera sentencia. Antes de un bloque o lnea siempre de comentario. Entre secciones lgica dentro de un mtodo para mejorar la legibilidad.

8.2 Espacios en Blanco Espacios en blanco se podran usar en las siguientes circunstancias: Una palabra clave seguido de un parntesis debe ser separada por un espacio. Ejemplo: while (true) { ... } Un espacio en blanco puede aparecer despus de comas en una lista de argumentos. Todos los operadores binarios de excepcin. Deben ser separados de sus operadores por espacios. a += c + d; a = (a + b) / (c * d); while (d++ = s++) { n++; } printSize("size is " + foo + "\n"); La expresin dentro de una sentencia for debe ser separada de espacio en blanco. Ejemplo: for (expr1; expr2; expr3)

Casts son seguidos de espacios en blanco. Ejemplo:

myMethod((byte) aNum, (Object) x); myMethod((int) (cp + 5), ((int) (i + 3)) + 1); 9 Convencin de Nombres

Las Convenciones de Nombres hacen los programas ms entendibles ya son fciles de leerlos. Estos pueden dar informacin acerca de la funcin del identificador el cual puede ser de ayuda para entender el cdigo. Tipo de Identifica dor El prefijo de un nico nombre de paquete es siempre escrito en letras ASCII Reglas para Nombrado Ejemplos

minsculas y son uno de los ms altos niveles de nombres de dominio,

actualmente com, edu, gov, mil, net, org. Componentes subsiguientes del nombre Paquetes del paquete varan de acuerdo a las convenciones de nombre de la propia organizacin. especifica directorio Como convenciones nombres una se de com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.chees e

que

ciertos

componen proyecto,

divisin, o

departamento,

maquina

nombres de acceso. Nombres de clases son sustantivos, en casos mixtos con la primera letra de cada palabra interna en mayscula. Tratar de Clases dejar tus nombres de clases simples y descriptivas. Usar palabras completas, class Raster; class ImageSprite;

evitar acrnimos y abreviaciones. Interfaces son nombrados iguales que las Interfaces clases. Mtodos son verbos, pueden ser mixtos: Mtodos con la primera letra en minscula y la letra de cada palabra interna en correr(); correrRapido(); getBackground(); interface RasterDelegate; interface Storing;

mayscula. A excepcin de las variables, todas las instancias de clase son mixtas con

minscula la primera letra. Las palabras internas empiezan con mayscula. Los nombres de variables no empiezan con carcter underscore _ o signo dolar $. Aun cuando permitan a ambos. Nombres Variables de variables son cortos y int char float i; c; myWidth;

significativos. La eleccin de un nombre de variable es mnemnico. Variables de un solo carcter debera ser evitados, excepto Nombres para variables de temporales. variables

comunes

temporales son i, j, k, m, y n para integres; c, d y e para caracteres. Los nombres de variables declarados static final MIN_WIDTH = 4; static final MAX_WIDTH = 999; static final GET_THE_CPU = 1; int int int

como constantes en una clase son todo Constantes en mayscula y con underscore ("_") para separar entre palabra.

10 Prcticas De Programacin

10.1 Proveer Acceso A Intancias Y Variables De Clase No hacer ninguna instancia o variable de clase sin una buena razn. A menudo las variables instanciadas no necesitan estar explcitamente obtenidas o puestas a menudo sucede como un efecto secundario de los mtodos que llaman.

Un ejemplo de una publica instancia de variable apropiada es el caso donde la clase es esencialmente una estructura de datos, sin comportamiento, en otras palabras,

si tu has usado una estructura en vez de una clase, entonces es apropiado hacer la instancia de variable de clase publica.

10.2 Referencia a Variables de Clases y Mtodos Evitar usar un objeto para acceder a una variable o mtodo de una clase esttica. Use en vez de eso el nombre de la clase. Por Ejemplo: classMethod(); //OK AClass.classMethod(); //OK anObject.classMethod(); //EVITAR! 10.3 Constantes Constantes numricos no son codificadas directamente, excepto de -1, 0 y 1, los cuales pueden aparecer como valor de un contador para una sentencia for.

10.4 Variable Assignments Evitar asignar muchas variables en el mismo valor de una simple sentencia. Es muy difcil de leer. Ejemplo: fooBar.fChar = barFoo.lchar = 'c'; // AVOID! No usar operadores de asignacin en lugar donde estos pueden ser fcilmente confundidos con un operador de igualdad. Ejemplo: if (c++ = d++) { // EVITAR! (Java disallows) ... } should be written as if ((c++ = d++) != 0) { ... } No usar asignadores en tentativa de mejorar la performance. Esta es una tarea del compilador. Ejemplo: d = (a = b + c) + r; should be written as a = b + c; d = a + r; // AVOID!

10.5 Buenas Prcticas a considerar

10.5.1 Parntesis Es generalmente Buena idea usar parntesis generosamente en expresiones que envuelven operaciones mixtas para evitar problemas de preferencias de operador. Incluso si la preferencia del operador le parece clara, esto no podra ser para otros, no se puede asumir que otros programadores conocen la preferencia que usted si lo conoce. if (a == b && c == d) // EVITAR! if ((a == b) && (c == d)) // CORRECTO 10.5.2 Retornando Valores Trarta de hacer que la estructura de su programa retorne de la mejor manera. if (booleanExpression) { return true; } else { return false; } Podrias hacerlo de la siguiente manera. return booleanExpression; Similarmente, if (condicion) { return x; } return y; Se pordia escribir como return (condition ? x : y); 10.5.3 Expresiones Antes ? En El Operador Condicional Si una expresin contiene un operador binario aparece antes del ? en el operador ternario ?:, este podra estar en parntesis. Ejemplo: (x >= 0) ? x : -x; 10.5.4 Comentarios Especiales Use XXX en un comentario para sealar algo que es falso. Use FIXME para sealar algo que es falso y daado.

11 - Ejemplos de Cdigo

11.1 Ejemplo de Archivo de Fuentes Java El siguiente ejemplo muestra como formatear un archive Java que contiene una clase publica. Las Interfaces son formateadas de modo similar. /* * @(#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 * All rights reserved. * * */ package java.blah; import java.blah.blahdy.BlahBlah; /** * Descripcion de clase aqui. * * @version 1.82 18 Mar 2008 * @author Firstname Lastname */ public class Blah extends SomeClass { /* Un comentario de implementacin de clases aqu. */ /** classVar1 comentario de documentacin */ public static int classVar1; /** * classVar2 comentarios de documentacin que ocupan * mas de una linea */ private static Object classVar2; /** instanceVar1 comentario de documentacin */ public Object instanceVar1; /** instanceVar2 comentario de documentacin */ protected int instanceVar2; /** instanceVar3 comentario de documentacin */ private Object[] instanceVar3; /** * ...constructor Blah comentario de documentacin... */ public Blah() { // ...implementacin inicia aqu e... } /** * ...method doSomething comentario de documentacin... */ public void doSomething() { // ...implementacin inicia aqu...

} /** * ...method doSomethingElse comentario de documentacin... * @param someParam descripcion */ public void doSomethingElse(Object someParam) { // ...implementacin inicia aqu... }