anexo 7. normas de código
DESCRIPTION
Anexo 7. Normas de CódigoTRANSCRIPT
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