Está en la página 1de 16

ESTNDAR DE CODIFICACIN JEE ESTNDAR DE CODIFICACIN JEE

21 de octubre de 2011 Versin 1

ESTNDAR DE CODIFICACIN JEE

Hoja de control documental


Realizado por Revisado por Aprobado por Grupo de Arquitectura JEE Fecha Fecha Fecha 21/10/2011

Control de versiones
Versin Fecha Descripcin

Lista de distribucin
Nombre Rol Organizacin

Documentos relacionados
Nombre Estndar de codificacin JEE CheckList URL http://amap.cantabria.es/amap/bin/download/AMAP15/n ormas/EstandardeCodificacionenJEEChecklistv11.pdf

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE

1.NDICE
1.NDICE ....................................................................................................................3 2.INTRODUCCIN.......................................................................................................4 2.1.OBJETIVOS....................................................................................................4 2.2.ALCANCE......................................................................................................4 2.3.DEFINICIONES Y ACRNIMOS.......................................................................4 2.4.DOCUMENTOS RELACIONADOS....................................................................4 3.CONVENCIONES DE CDIGO EN DESARROLLO JAVA ENTERPRISE EDITION...........5 3.1.GENERALIDADES..........................................................................................5 3.1.1.Encoding............................................................................................5 3.1.2.Identificador de la aplicacin.............................................................5 3.1.3.Estructura de directorios....................................................................5 4.ESTNDAR DE CODIFICACIN JAVA.........................................................................9 4.1.NOMENCLATURA...........................................................................................9 4.1.1.Paquetes............................................................................................9 4.1.2.Nombres de Interfaces.....................................................................10 4.1.3.Nombres de Clases..........................................................................10 4.1.4.Nombres especficos de gestiones...................................................11 4.1.5.Mtodos...........................................................................................11 4.1.6.Variables..........................................................................................11 4.1.7.Constantes.......................................................................................12 4.2.ESTILO DE CONDIFICACIN........................................................................12 4.2.1.Comentarios.....................................................................................12 4.2.2.Comentarios de Documentacin (Javadoc)......................................12 4.2.3.Declaraciones..................................................................................14 4.2.4.Sentencias.......................................................................................14 4.2.5.Buenas Prcticas..............................................................................14 4.2.5.1.Constantes....................................................................................14 4.2.5.2.Propiedades..................................................................................15 4.2.5.3.Mtodos........................................................................................15 5.ESTNDAR DE CODIFICACIN WEB......................................................................16 5.1.NOMENCLATURA.........................................................................................16 5.2.CDIGO JSP/HTML .....................................................................................16

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


2.INTRODUCCIN
En este documento se describe el estndar de codificacin para los proyectos que se desarrollen dentro de la tecnologa JEE.

2.1.OBJETIVOS
Los objetivos del presente documento son: Definir las convenciones de codificacin para el desarrollo en JEE. Describir las convenciones de comentarios (tags) para la generacin de documentacin con Javadoc. Definir el conjunto de reglas que componen el estndar de codificacin y que se van a verificar en los anlisis de cdigo.

2.2.ALCANCE
Este estndar es aplicable a todos los proyectos que se desarrollen con tecnologa JEE.

2.3.DEFINICIONES Y ACRNIMOS

Acrnimo JEE JSP Java Enterprise Edition Java Server Pages

Definicin

2.4.DOCUMENTOS RELACIONADOS

Referencia http://www.oracle.com/technetwork/java/codeconv138413.html http://java.sun.com/blueprints/code/namingconv entions.html http://maven.apache.org/guides/introduction/intr oduction-to-the-standard-directory-layout.html Http://amap.cantabria.es

Nombre Code Conventions for the Java Programming Language. Guidelines, Patterns, and code for end-to-end Java applications Maven Introduction to the Standard Directory Layout. AMAP 1.5

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


3.CONVENCIONES DE CDIGO EN DESARROLLO JAVA ENTERPRISE EDITION
En general, se seguirn las convenciones de SUN Microsystems, para el desarrollo con JEE, JAVA y JSP que se pueden consultar desde el siguiente enlace: http://java.sun.com/blueprints/code/namingconventions.html No hay particularizaciones sobre las convenciones de SUN para la nomenclatura de los componentes JEE. Las convenciones de codificacin en JAVA sern las de SUN Microsystems (http://www.oracle.com/technetwork/java/codeconv-138413.html). Las variaciones sobre estas normas se especifican a continuacin.

3.1.GENERALIDADES 3.1.1.Encoding
Para evitar problemas de portabilidad todos los ficheros debern ir codificados en UTF8. (http://amap.cantabria.es/amap/bin/view/AMAP15/eclipse-encoding)

3.1.2.Identificador de la aplicacin
A cada aplicacin se le asignara un identificador nico (ID_APP) que se utilizar siempre que sea necesario hacer una referencia a la aplicacin. Este cdigo ser asignado por el Gobierno de Cantabria. En el caso de que la aplicacin est compuesta por varios mdulos se le asignar un cdigo de 4 caracteres a cada mdulo. Los cdigos sern independientes del nombre del proyecto y su razn de ser es la identificacin inmediata de los componentes de una aplicacin para toda la organizacin.

3.1.3.Estructura de directorios
La estructura de directorios para cada aplicacin ser la estndar de definida por el proyecto Maven (http://maven.apache.org/guides/introduction/introduction-to-thestandard-directory-layout.html). A continuacin se detalla la estructura que debera tener una aplicacin Web.

Directorio ID_APP ID_APP src

Descripcin

Cdigo fuente

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


Directorio ID_APP ID_APP ID_APP src src src main main main java config Descripcin Cdigo fuente principal Cdigo fuente Java Ficheros adaptados a cada entorno [desarrollo] Ficheros especficos del entorno de desarrollo Ficheros especficos del entorno de preproduccin Ficheros especficos del entorno de produccin Recursos de la aplicacin (applicationcontext.xml, ficheros de i18n, etc) webapp webapp webapp webapp webapp webapp webapp webapp static static static static META-INF WEB-INF WEB-INF config Ficheros de 6 js css images Ficheros de la aplicacin web Ficheros estticos Ficheros Javascript (.js) Hojas de estilo (.css) Imgenes

ID_APP

src

main

config

ID_APP

src

main

config

[preproduccion]

ID_APP

src

main

config

[produccion]

ID_APP

src

main

ID_APP ID_APP ID_APP ID_APP ID_APP ID_APP ID_APP ID_APP

src src src src src src src src

main main main main main main main main

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


Directorio Descripcin configuracin (strutsconfig.xml, etc) ID_APP ID_APP ID_APP ID_APP ID_APP ID_APP src src src src src src main main main main site test webapp webapp webapp webapp WEB-INF WEB-INF WEB-INF WEB-INF jsp tags tlds lib Tag Library Descriptors Librerias (.jars) Documentacin de la aplicacin Cdigo fuente de test Ficheros .jsp

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE

4.ESTNDAR DE CODIFICACIN JAVA


4.1.NOMENCLATURA
El idioma por defecto a la hora de dar sentido funcional al nombre de clases, variables, constantes, etc. ser una mezcla entre la nomenclatura tradicional en ingls y la nomenclatura funcional adoptada. Resumiendo, aquella codificacin que por estandardizacin y/o aceptacin se pueda escribir en ingls se mantendr as por convenio, casos como insert, update,

delete, create, retrieve, list, set, get, newInstance, Delegate.


Para la parte funcional se utilizara castellano, por lo tanto la nomenclatura de los mtodos ser: getListEmpresa en sustitucin de getListCompany o insertBanco en lugar de insertarBanco.

4.1.1.Paquetes
Por defecto todos los paquetes se escribirn en minsculas y sin utilizar caracteres especiales. El paquete base queda definido como es.gobcantabria, en este paquete no se definir ninguna clase. Se tendr, as mismo, otro nivel extra dentro del paquete definido como el nombre del proyecto o del mdulo (Ej. es.gobcantabria.xxxx ). Si existiera una parte comn a varios de estos mdulos, el nombre de los paquetes comenzarn por: es.gobcantabria.common La estructura en rbol de los paquetes siguientes a partir de este ltimo se define como sigue: (presuponiendo que se trata de una aplicacin web multicapa). bussines dao imp

exception service util dto report

util

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


web actions report

filter form report

listener

4.1.2.Nombres de Interfaces
Los nombres de interfaces utilizarn el sufijo Interface y estarn compuestos por palabras con la primera letra en mayscula (CamelCase). Se debe evitar el uso de abreviaciones que dificulten la comprensin del cdigo. Ejemplo: ConexionInterface,

ComponenteTablaInterface

4.1.3.Nombres de Clases
Los nombres de clases deben ser mezclas de maysculas y minsculas, con la primera letra de cada palabra interna en maysculas (CamelCase). Debemos intentar mantener los nombres de clases simples y descriptivos. Debemos usar palabras completas y evitar acrnimos y abreviaturas (se permiten DAO, DTO, URL, HTML, etc.). Si la clase cumpliese algn patrn determinado o tuviese una funcionalidad especfica es recomendable definirlo en el nombre.

Paquete bussines.dao bussines.dao.impl bussines.exception bussines.service bussines.util bussines.dto bussines.dto.report

Funcionalidad Data Access Object (Interface) Data Access Object (Implementation) Excepciones Service Helper Data Transfer Objects

Nombre <nombre>DAO <nombre>DAOImpl <nombre>Exception <nombre>Service <nombre>Helper <nombre>DTO

Estndar de Codificacin J2EE

10

ESTNDAR DE CODIFICACIN JEE


Paquete util web.actions web.actions.report web.filter web.form web.form.report web.listener web.util web.util.validator Listener Helper Validator <nombre>Listener <nombre>Helper <nombre>Validator Filter Form <nombre>Filter <nombre>Form Funcionalidad Clases de constantes. Actions Nombre <scope>Keys <nombre>Keys <nombre>Action

4.1.4.Nombres especficos de gestiones


Cuando se trata de gestionar una entidad determinada (Ej. Usuario) se definen los nombres de clases, dems ficheros implicados con la siguientes reglas: Clase: <<FuncionalidadGenerica>><<Entidad>><<Especificacin de Clase>> Ejemplo: Usuario

UsuarioAction, FindUsuarioAction 4.1.5.Mtodos


Los mtodos debern ser verbos (en infinitivo), en maysculas y minsculas con la primera letra del nombre en minsculas, y con la primera letra de cada palabra interna en maysculas (lowerCamelCase). No se permiten caracteres especiales. El nombre ha de ser lo suficientemente descriptivo, no importando a priori la longitud del mismo.

4.1.6.Variables
Los nombres de las variables tanto de instancia como estticas reciben el mismo tratamiento que para los mtodos, con la salvedad de que aqu s importa ms la relacin entre la regla mnemnica y la longitud del nombre. Ejemplo: Correctos: diaCalculo, fechaIncoporacion Incorrectos: dC, DCal, fI, FI

Estndar de Codificacin J2EE

11

ESTNDAR DE CODIFICACIN JEE


Se evitar en la medida de lo posible la utilizacin de caracteres especiales, as como nombre sin ningn tipo de significado funcional. Las excepciones son las variables utilizadas en bucles for, para esos casos se permite utilizar i, j, k, l y siempre en ese orden de anidamiento. El primer bucle siempre ser el que tenga la variable definir para el bucle en cuestin).

i como iterador. (Esta variable se

4.1.7.Constantes
Los nombres de constantes de clases deberan escribirse todo en maysculas con las palabras separadas por subrayados (_). Todas sern declaradas como public static final.

public static "urlServicio";

final

String

PROPERTY_URL_SERVICIO

4.2.ESTILO DE CONDIFICACIN 4.2.1.Comentarios


Los comentarios sern utilizados para dar informacin adicional al desarrollador sobre la implementacin del diseo de la clase. Se tiene, por tanto, que evitar referencias al diseo funcional de la misma. El uso abusivo de los comentarios es desaconsejable, principalmente por el trabajo extra necesario para su correcto mantenimiento. Es preferible redisear el cdigo para una mejor compresin del mismo. Se tienen que evitar el uso de caracteres especiales dentro de los comentarios as como el uso de cajas u otro tipo de grfico creado mediante cdigos ASCII. La estructura de los diferentes tipos de comentarios y su uso general se presenta en la clase base de codificacin.

4.2.2.Comentarios de Documentacin (Javadoc)


Como norma es obligatorio proporcionar un comentario de documentacin por cada clase / interface, mtodo, propiedad o constante creado. Son obligatorios los siguientes comentarios de documentacin: Comentario de la clase / interface: Prescripcin genrica de la clase y su responsabilidad. 12

Estndar de Codificacin J2EE

ESTNDAR DE CODIFICACIN JEE


Autor.

Todas las variables tipo private o protected han de ser obligatoriamente comentadas. Reglas generales a la hora de escribir comentarios de documentacin. Siempre se escribe en tercera persona. Los caracteres especiales tales como tildes y ees se han de codificar con su cdigo HTML correspondiente. Las descripciones siempre deberan empezar por un verbo.

En cuanto a los tags utilizados el orden de los mismos es el siguiente:

@param seguido de el nombre del parmetro e indentada la descripcin del


mismo. Usualmente esta descripcin ser una frase corta que comienza definiendo el tipo del parmetro.

@param alturaCaja @param longitudCaja

Entero que define la altura de la caja en pxeles Flotante que define la longitud de la caja en pxeles

@return este tag no aparece para aquellos mtodos que retornan void.
Por lo dems se comporta como el tag anterior

@throws Descripcin breve de la posible causa de la excepcin. @see Su uso queda restringido en cuanto a cantidad de los mismos como
con el atributo @link.

Los dems tags permitidos (@since, @serial, etc..) el uso es menos comn y por lo tanto no se define una manera de utilizarlos. Usar el atributo <code> para las palabras reservadas de java, nombres de clases, mtodos, interfaces, propiedades, argumentos y ejemplos de cdigo. El uso del atributo @link tendr que ser mnimo, para evitar llenar el documento de enlaces. Como norma general solo se incluirn links cuando la referencia sea necesaria y slo en la primera aparicin de la misma. Para distinguir entre dos mtodos con el mismo nombre pero diferentes parmetros de entrada se utilizaran el nombre del mtodo seguido por los argumentos del mismo entre parntesis.

Estndar de Codificacin J2EE

13

ESTNDAR DE CODIFICACIN JEE


4.2.3.Declaraciones
Para la declaracin de las variables se utiliza una declaracin de cada vez y no se permiten dejar variables locales sin inicializar salvo en el caso de que sean propiedades de un objeto bean. La codificacin correcta sera:

public static Integer entero = new Integer(0);


La declaracin de las variables locales a una clase, mtodo o bloque de cdigo se realizan al principio del mismo y no justo antes de necesitarse la utilizacin de la variable. La nica excepcin a esta regla son las variables que gestionan los bucles

for.

Las variables de avance de bucles for no podrn ser modificadas de ninguna manera fuera de la propia sentencia del bucle. La duplicidad de los nombres de variables en diferentes niveles dentro de la misma clase se tiene que evitar.

4.2.4.Sentencias
Normas bsicas son : Una sentencia por lnea de cdigo. Todo bloque de sentencias entre llaves, aunque sea una sola sentencia despus de un if.

La declaracin de los bucles for sern usualmente de la forma :

for (int i = 0; i < condicion ; i++)

Son obligatorias las tres condiciones del bucle for: inicializacin, condicin de finalizacin y actualizacin del valor de la variable de avance. La variable de avance del bucle nunca podr ser modificada dentro del propio bucle.

4.2.5.Buenas Prcticas 4.2.5.1.Constantes


Como norma general todas las constantes numricas no deberan codificarse directamente, salvo la excepcin de -1, 0 y 1. Estndar de Codificacin J2EE 14

ESTNDAR DE CODIFICACIN JEE


4.2.5.2.Propiedades
El acceso/modificacin de las propiedades de una clase (no constantes) siempre mediante mtodos de acceso get/set. La asignacin de variables / propiedades no podr ser consecutiva.

Variable1 = variable2 = hola mundo

No vlido

No utilizar el operador asignacin en sitios donde se pueda confundir con el operador igualdad. Ni dentro de expresiones complejas.

If (c == a) { d = (a = (b+c))+z }

4.2.5.3.Mtodos
Como norma general no se debe acceder a un mtodo esttico desde una instancia de una clase, debemos utilizar la clase en s misma.

Estndar de Codificacin J2EE

15

ESTNDAR DE CODIFICACIN JEE

5.ESTNDAR DE CODIFICACIN WEB


5.1.NOMENCLATURA
Los nombres de los ficheros JSP, usualmente compuestos por varias palabras, empiezan por una palabra en minscula seguido del resto con la primera letra en mayscula (lowerCamelCase).

5.2.CDIGO JSP/HTML
No se permite el uso de Scriptlets. Usar Tag Libraries y EL (Expression Language) en su lugar. Siempre que se pueda utilizar una etiqueta JSP estndar no se utilizar ninguna otra. Son validas todas aquellas etiquetas JSP definidas para el proyecto (Struts, JSTL, etc).

No se permite el uso de includes dinmicos. En caso de Struts usar el plugin de Tiles en su lugar.

Los atributos de los elementos HTML debern llevar comillas dobles. No esta permitido el uso de Javascript para la creacin de contenido. Se debe usar CSS para aplicar estilos. No se permite el uso de los siguientes elementos HTML: applet, basefont, center, dir, font, isindex, menu, s, strike, u. No se permite el uso de atributos HTML 4 obsoletos (deprecated): http://www.w3.org/TR/html4/index/attributes.html. Evitar el uso de comentarios en HTML. Todos los literales debern ser internacionalizados (i18n) Se definirn todas las etiquetas en un fichero externo (resource bundle).

Estndar de Codificacin J2EE

16