ANEXO a la Gua de Estndares

Normas de Codificacinndice

41Introduccin

42Juego de Caracteres

42.1Consideraciones generales

42.2Pginas estticas HTML y dinmicas JSP

52.3Ficheros XML

52.4Configuracin local del servidor

53Normativa del cdigo java

53.1Convenciones de nombrado

53.1.1Paquetes

63.1.2Clases

63.1.3Interfaces

63.1.4Constantes

63.1.5Variables

73.1.6Variables locales

73.1.7Parmetros

73.1.8Mtodos

73.1.9Mtodos Set y Get

73.1.10Mtodos de conversin de tipos

83.2Convenciones de documentacin

83.2.1Javadoc

83.2.2Paquetes

83.2.3Clases e Interfaces

83.2.4Mtodos

93.2.5Constantes, variables de Clase y variables de Instancia

93.3Normas de codificacin

103.3.1Normas obligatorias para el despliegue.

113.3.2Normas automticas y obligatorias

133.3.3Normas de cdigo duplicado

143.3.4Normas comprobadas por mtrica

173.3.5Normas manuales

183.4Gestin de errores y ficheros de traza de la aplicacin

204Normativa de servicios web

204.1Interface del servicio web

204.1.1Cabeceras WSDL

214.1.2Inline WSDL

214.1.3Namespaces

1 Introduccin

El siguiente documento contiene las recomendaciones y la normativa de calidad que debe cumplir el cdigo fuente de las aplicaciones.

Estas normas son de obligado cumplimiento aunque podrn considerarse excepciones, que sern propuestas por el equipo y analizadas conjuntamente con el Comit de Estndares.

Durante el control de calidad se realizar una comprobacin lo ms automtica posible que permita generar un informe de cumplimiento de la normativa as como una mtrica de calidad asociada.

Las herramientas de anlisis esttico del cdigo son gratuitas y de libre distribucin. Esto implica que cada proveedor puede realizar tambin dicha comprobacin antes de realizar la entrega usando el conjunto de reglas proporcionadas por el IAM.2 Juego de Caracteres2 Consideraciones generales

Para evitar problemas por el uso de distintas configuraciones en los ficheros de cdigo fuente java, los ficheros de configuracin, los ficheros de recursos de idiomas y scripts de base de datos deben estar codificadas en UTF-8, tanto para ficheros Java, pginas HTML, JSP, scripts de base de datos, etc.2 Pginas estticas HTML y dinmicas JSP

Los parmetros de la peticin usarn el mismo juego de caracteres que el formulario, por lo que conviene hacer una declaracin explcita del juego de caracteres: Esto generar la etiqueta META en la pgina HTML con la indicacin del charset=UTF-8

- En una JSP, la directiva de pgina contentType puede ser utilizada con este mismo fin:

2 Ficheros XML

Los ficheros XML deben estar codificados en UTF-8, de modo que deben de comenzar siempre por:

2 Configuracin local del servidor

Al realizar la codificacin de un proyecto, se debe independizar el tratamiento de nmeros, fechas, de la configuracin local del servidor.

Para ello se deben usar siempre que sea posible los mtodos de las clases de manipulacin de fechas y nmeros que soporten el paso de un objeto de tipo Locale. Por ejemplo usar el constructor SimpleDateFormat (String dateFormat, Locale locale) o el mtodo NumberFormat.getInstance(Locale locale).

3 Normativa del cdigo java

3 Convenciones de nombrado

Las convenciones de nombrado permiten que las aplicaciones desarrolladas sean ms fciles de leer y de mantener, adems de un punto de partida para la calidad de aplicaciones.

De modo general se siguen los criterios de nombrado definidos en la web de Oracle: http://www.oracle.com/technetwork/java/codeconvtoc-136057.html. A partir de estos criterios se recomienda seguir la siguiente nomenclatura para los distintos elementos java.

3 Paquetes

Los nombres de paquetes deben estar en minsculas.

Evitar tener ms de 7 niveles de paquetes.

Usar nombres descriptivos de menos de 15 caracteres.

Los nombres de paquete son de la forma es.iam.[proyecto].[funcionalidad].[capa].* donde el significado es:

[proyecto] ser el acrnimo de proyecto de 5 letras.

[funcionalidad] se refiere a la aplicacin, proceso de negocio o caso de uso que implementa.

[capa] indica la capa o servicio de la arquitectura donde se localiza la clase o interface. (view, business, persistence, service).

Este criterio es opcional para paquetes ya existentes.

Los paquetes que contienen las excepciones de una determinada capa sern de la forma es.iam.[proyecto].[funcionalidad].[capa].*.exception3 Clases

El nombre de la clase debe empezar por mayscula seguido de minsculas.

Los nombres de las clases deben ser simples y describir la funcionalidad proporcionada.

Utilizar nombres significativos y completos; evitar utilizar acrnimos y abreviaturas.

Si la clase tiene un nombre compuesto, utilizar una combinacin minscula / mayscula para cada nombre, en lugar del carcter _ (Ej.: GestorArchivos en lugar de Gestor_Archivos o Gestor _ archivos).

Las clases de Excepciones terminarn siempre en Exception. (Ej.: FicheroNoEncontradoException)

3 Interfaces

Los nombres de las interfaces siguen las mismas reglas que los nombres de las clases.

Los nombres de las interfaces deben empezar por la letra I mayscula para distinguir Clases e Interfaces.

3 Constantes

Los identificadores de constantes deben ser descriptivos y todos en mayscula.

Para nombres compuestos usamos nombres en maysculas separados por _. (EJ.:IMPUESTO_SOCIEDADES)3 Variables

Los identificadores de variable deben empezar por minscula y no deben comenzar por _ o $.

Para nombres compuestos, utilizar una combinacin mayscula / minscula en lugar del carcter _. (EJ.: identificadorCiudadano en lugar de idenficador_ciudadano)3 Variables locales

Los identificadores de variables locales deben ser significativos. Se pueden usar nombres cortos de una letra para variables temporales de usar y tirar: i, j, k, n, m para tipos enteros. c, d, e para tipos carcter.3 Parmetros

Los identificadores de parmetros de mtodos deben seguir las mismas normas que las variables.

3 Mtodos

Los nombres de mtodos deben comenzar con una letra minscula.

Para identificadores compuestos, utiliza una combinacin mayscula / minscula en lugar del carcter _ (Ej. generaInforme) El nombre del mtodo no debe superar los 30 caracteres de longitud.3 Mtodos Set y Get

Son los mtodos que se utilizan para encapsular el acceso a una variable de la clase que debe ser privada. Estos mtodos se denominan igual que la variable de la clase que encapsulan, con la salvedad de que se substituye el prefijo de la variable por los siguientes prefijos: set para el setter, es decir, para el mtodo que asigna un valor a la propiedad de la clase.

is para el getter de una propiedad booleana, es decir, para el mtodo que devuelve el valor de una propiedad booleana de la clase.

get para el getter de una variable no booleana de la clase. 3 Mtodos de conversin de tipos

Si la clase dispone de un mtodo de conversin a otro tipo, denominarlo con el prefijo to seguido del nombre del tipo, de forma anloga a como hace API de JAVA con el mtodo toString(). (EJ.:toXML())3 Convenciones de documentacin

3 Javadoc

La herramienta Javadoc genera documentacin en formato HTML a partir de los comentarios de tipo Javadoc. Se debe utilizar este tipo de comentarios para ir documentando el cdigo segn se genera o revisa. Utilizar las siguientes etiquetas HTML para mejorar la legibilidad de los comentarios:

para separar prrafos.

... o ... para fragmentos pequeos de cdigo.

... para fragmentos largos de cdigo. Se seguirn las siguientes normas para documentar el cdigo java: Se debe tener documentado todo el API que exporta tu clase, es decir, las variables, constantes, mtodos y constructores public y protected.

Utilizar comentarios Javadoc para explicar qu hace la clase, o mtodo, para qu sirve una interface, cul es el propsito de una variable o constante. Es recomendable no indicar el cmo lo hace ya que es fcil que el comentario se quede desactualizado.

3 Paquetes

Incluir en cada directorio un fichero package.html o package-info.java en el que documente el propsito del paquete.

3 Clases e Interfaces

Incluir antes de la declaracin de cada clase o interface una descripcin del mismo en formato Javadoc

Finalizar la descripcin con las etiquetas siguientes:

@author - para indicar el autor o autores.

3 Mtodos

Al documentar un mtodo se establece un contrato entre el que desarrolla la clase o interface y quien vaya a usarlo.

En este contrato se debe especificar lo que se espera de los parmetros de entrada, las acciones que se comprometen a realizar y las excepciones que se van a lanzar si el cliente no cumple su parte del contrato o si se produce un error durante la ejecucin.

Utilizar comentarios Javadoc para documentar este contrato:

Propsito del mtodo. Parmetros del mtodo. Utilizar la etiqueta @param de Javadoc. En caso de restricciones en los parmetros indicarlo aqu. (Ej.: El valor no puede ser nulo)

Valor de retorno, si aplica. Utilizar la etiqueta @return de Javadoc. Excepciones que puede lanzar el mtodo. Utilizar la etiqueta @throws de Javadoc. Explicar las situaciones dnde producir estas excepciones y documentar todas las excepciones que puede lanzar el mtodo.

3 Constantes, variables de Clase y variables de Instancia

Utilizar comentarios Javadoc para documentar como mnimo las constantes, variables de clase y variables de instancia que exporta la clase (public y protected).3 Normas de codificacin

A continuacin tenemos la siguiente tabla con una relacin de las normas de obligado cumplimiento para el cdigo fuente java de todas las aplicaciones.

Se usarn las herramientas PMD (http://pmd.sourceforge.net) y Checkstyle (http://checkstyle.sourceforge.net/) para el anlisis esttico y automtico del cdigo.

Las normas pueden comprobarse en RSA instalando los plugin necesarios.

Con maven se pueden comprobar configurando de forma correcta la seccin de reporting del pom.

Para comprobar las normas con maven se deben ejecutar los siguientes comandos.

Tras esto se debe acceder a la carpeta donde se ha configurado la generacin de la documentacin abrir el archivo index.html y comprobar el reporting de todos los mdulos del proyecto.

3 Normas obligatorias para el despliegue.

Estas normas se comprobaran de forma automtica sobre el cdigo y son de obligado cumplimiento si se solicita un despliegue. En caso de existir un incumplimiento en estas reglas se parar la solicitud de despliegue.

NormaDescripcinComprobarUmbral

GDoNotCallGarbageCollectionExplicitlyNo llamar explcitamente al recolector de basura.PMD

GUncommentedMainNo se deben incluir mtodos main en el cdigo de la aplicacin.Checkstyle

GRegExpNo se deben usar en el cdigo las siguientes instrucciones.

System.setProperties System.exit System.err

System.out setMaxInactiveInterval

Checkstyle

RRegExpNo se deben usar en el cdigo las siguientes instrucciones.

Thread.sleepCheckstyle

RUnnecessaryCaseChangeUsar equalsIgnoreCase() en lugar de toLowerCase() / toUpperCase().equals para comparar cadenas String.PMD

RSuppressWarningsNo usar la anotacin @SuppressWarnings para evitar los warnings del compiladorCheckstyle

RusoSingleThreadModelNo se permite el uso del paquete: javax.servlet.SingleThreadModelPMD

GDoNotUseThreads

No crear threads propios desde el cdigo. No tienen accesos a los recursos y contexto J2EE. No son controlables por el servidor de aplicaciones. Usar AsynchronousBeans o JMS para la programacin de procesos asncronos.PMD.

MSimpleDateFormatNeedsLocaleSe debe desacoplar el cdigo de la configuracin concreta del servidor.

Cuando se cree una instancia de SimpleDateFormat se debe especificar el locale.PMD

MNumberFormatSinLocaleSe debe desacoplar el cdigo de la configuracin concreta del servidor.

Cuando se cree una instancia de NumberFormat se debe especificar el locale.PMD

3 Normas automticas y obligatorias

Consideramos las siguientes normas que se pueden comprobar automticamente a nivel individual y son de obligado cumplimiento.

El umbral indica si alguna regla PMD o Checkstyle no puede superar un valor mnimo establecido.

NormaDescripcinComprobarUmbral

AssignmentToNonFinalStaticNo asignar valores inseguros a variables o propiedades estticas. PMD

AvoidCatchingNPENo capturar excepciones NullPointerException.PMD

AvoidPrintStackTraceNo se permite el uso de llamadas ex.printStackTrace().PMD

AvoidThrowingNullPointerExceptionNo disparar excepciones NullPointerException.PMD

AvoidThrowingRawExceptionTypesNo disparar excepciones primarias, en su lugar lanzar subclases de ellas.PMD

BooleanExpressionComplexityEl mximo de operadores booleanos (&&, || y ^) permitidos.Checkstyle6

ClassNamingConventionsLos nombres de las clases deben empezar por letra mayscula.PMD

ConstructorCallsOverridableMethodLos constructores no deben llamar a mtodos sobrescritos.PMD

CyclomaticComplexityLa complejidad ciclomtica de cada mtodo.PMD25

DoNotUseThreadsNo crear threads propios desde el cdigo. No tienen accesos a los recursos y contexto J2EE. No son controlables por el servidor de aplicaciones. Usar AsynchronousBeans o JMS para la programacin de procesos asncronos.PMD.

ExcessiveClassLengthEl nmero mximo de lneas una clase.PMD2000

ExcessiveMethodLengthEl nmero mximo de lneas permitidas por mtodo.PMD200

ExcessiveParameterListEl nmero mximo de parmetros permitidos en un mtodo.PMD14

ExcessivePublicCountEl nmero mximo de mtodos y atributos pblicos declarados en una clase.PMD60

ExplicitInitializationNo se debe inicializar un campo al valor por defecto de su tipo (nulo para referencias u objetos, 0 para nmeros y char, y false para bolean, etc).Checkstyle

IllegalImportNo se permite el uso del paquete:

sun.*Checkstyle

usoNativeJdbcExtractorNo est permitido el uso de la clase:org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor.

PMD

MethodNamingConventionsLos nombres de mtodos deben empezar siempre por letra minscula.PMD

NoScriptletsNo se permite el uso de scriptlets en las pginas JSP.PMD

PackageDeclarationTodas las clases tienen una declaracin de paquete.Checkstyle

PackageNameLos paquetes deben llamarse de la forma es.iam.[proyecto]. Checkstyle

RegExpNo se permiten llamadas del tipo:

System.inCheckstyle

SignatureDeclareThrowsExceptionNo usar throws Exception en la declaracin del mtodo, usar una clase derivada de RuntimeException o una excepcin chequeada.PMD

SystemPrintlnNo se permite llamadas

System.out .print

System.err.printPMD

UnusedPrivateMethodNo se permiten mtodos privados declarados sin usar.PMD

UseArrayListInsteadOfVectorNo usar la coleccin Vector. En su lugar usar ArrayList.PMD

UseStringBufferForStringAppendsUsar StringBuffer y el mtodo append() en lugar de += para concatenar cadenas.PMD

3 Normas de cdigo duplicado

Se auditar el cdigo de forma automtica para limitar el uso de cdigo duplicado. La herramienta a usar ser el modulo CPD asociado con la librera PMD y tomando como base mnima de duplicacin aproximada de 5 lneas de cdigo fuente (100 tokens).

La existencia de bloques de cdigo duplicado que superen este lmite impuesto supondr un error que deber ser solucionado para poder realizar la aceptacin del cdigo entregado.

3 Normas comprobadas por mtrica

Se consideran aqu las normas que no siendo de obligado cumplimiento a nivel individual se comprueban automticamente por volumen a nivel de aplicacin.

El clculo se realiza con la siguiente frmula:

Porcentaje= Nmero total de violaciones/(Nmero de lneas de cdigo *100)

Solo se permitir un incumplimiento del 30% respecto a estas normas.

NormaDescripcinComprobarUmbral

AbstractNamingLos nombres de las clases abstractas deben empezar por AbstractXXX.PMD

AvoidDuplicateLiteralsEvitar literales duplicados, declarar el String como campo constante.PMD

AvoidStarImporNo se permite usar * en las declaraciones import.Checkstyle

AvoidUsingOctalValuesAl expresar valores decimales, no escribir ceros precedentes, ya que son tomados como valores octales.PMD

CompareObjectsWithEqualsComparar objetos con equals, no con ==.PMD

ConstantNameLas constantes deben ser expresadas con todas las letras en maysculas.Checkstyle

EmptyCatchBlockNo se permiten bloques catch vacos.PMD

EmptyFinallyBlockNo se permiten bloques finally vacos.PMD

EmptyIfStmtNo se permiten sentencias if sin contenido.PMD

EmptyStatementNotInLoopNo se permiten sentencias vacas excepto en bucles.PMD

EmptySwitchStatementsNo se permiten bloques switch vacas.PMD

EmptyTryBlockNo se permiten bloques try vacos.PMD

EmptyWhileStmtNo se permiten sentencias while sin contenido.PMD

EqualsNullNo usar equals() para comparar con null.PMD

FallThroughTodas las sentencias de un switch deben tener su sentencia de cierre (break, return, throw o continue).Checkstyle

ForBienFormadoUna sentencia for esta siempre bien formada. No estar bien formado tiene la parte de inicializacin, la expresin de salida y la de actualizacin.

Son validos los foreach.

Ejemplo:

for (int i=0;i