normas de desarrollo de aplicaciones para la dirección general de

DIRECCIÓN GENERAL
DE ORDENACIÓN DEL JUEGO
MINISTERIO DE HACIENDA Y
ADMINISTRACIONES PUBLICAS
S
U
B
D
NORMAS DE DESARROLLO DE APLICACIONES PARA LA
DIRECCIÓN GENERAL DE ORDENACIÓN DEL JUEGO:
JAVA
29/01/2013
Calle Atocha, 3
CORREO ELECTRÓNICO:
28012 MADRID
Página 1 de 17
TEL.:
FAX.:
Ministerio de Hacienda y
Página 2 de 17
Administraciones Públicas
CONTROL DE DOCUMENTACIÓN
TÍTULO DOCUMENTO:
NORMAS
DE
DESARROLLO
DE
APLICACIONES
PARA LA
DIRECCIÓN GENERAL DE ORDENACIÓN DEL JUEGO
HISTÓRICO DE VERSIONES
CÓDIGO
VERSIÓN
FECHA
AUTOR
RESUMEN DE LOS CAMBIOS PRODUCIDOS
1.0
08/01/2013 Héctor Gracia
Versión inicial
2.0
29/01/2013 Héctor Gracia
Se elimina la sección de Base de Datos y se redacta
como documento
HISTÓRICO DE CONTROL DE CALIDAD
PREPARADO
REVISADO
VERSIÓN
NOMBRE
FECHA
NOMBRE
FECHA
Ministerio de Hacienda y
Página 3 de 17
Administraciones Públicas
INDICE
Contents
Histórico de Versiones .............................................................................................. 3
Histórico de Control de Calidad ................................................................................ 3
1
Objetivo ............................................................................................................. 5
2
Introducción ....................................................................................................... 6
3
Normas de Estilo ............................................................................................... 7
4
3.1
Normas de Estilo ......................................................................................... 7
3.2
Criterios de Nomenclatura ........................................................................... 7
Normas de Codificación .................................................................................... 7
4.1
Reglas de PMD ........................................................................................... 7
4.2
Reglas de Checkstyle ................................................................................ 13
5
Inyección de Dependencias............................................................................. 16
6
Documentación del Código ............................................................................. 16
7
Duplicidad de Código ...................................................................................... 17
8
Visualización del Código ................................................................................. 17
Tabla 1- Reglas de Codificación ............................................................................. 12
Tabla 2- Reglas impuestas para la herramienta Checkstyle ................................... 16
Ministerio de Hacienda y
Página 4 de 17
Administraciones Públicas
1 Objetivo
El objetivo del presente documento es presentar las normas a seguir durante el desarrollo
de las aplicaciones informáticas que se desarrollarán para la DGOJ utilizando el lenguaje de
programación Java.
Ministerio de Hacienda y
Página 5 de 17
Administraciones Públicas
2 Introducción
Para un correcto desarrollo de aplicaciones de informáticas, así como para su
mantenimiento y puesta en producción es necesario seguir el conjunto de normas que se
detallan a continuación y que afectan a la codificación, integración e implantación de
dichos sistemas informáticos.
Ministerio de Hacienda y
Página 6 de 17
Administraciones Públicas
3 Normas de Estilo
3.1 Normas de Estilo
De base para todos los criterios de codificación se usarán las recomendaciones de Oracle
recogidos en el documento “Code Conventions for the Java Programming Language”
redactado en su momento por Sun y ahora perteneciente a Oracle. Puede consultarse en el
siguiente enlace: Code Conventions for the Java Programming Language.
Así mismo se utilizará la herramienta CHECKSTYLE para verificar que los desarrollos
cumplen con estos criterios.
3.2 Criterios de Nomenclatura
Los nombres de las tablas, clases, variables, métodos, etc. serán escritos en inglés si se
refieren a aspectos técnicos de la aplicación, y en español si se refieren a aspectos de
negocio que deben ser entendidos por el usuario final.
Los nombres de librerías deberán figurar en minúsculas y se incluirá su número de versión
dentro del fichero MANIFEST.
4 Normas de Codificación
A continuación se exponen las normas de codificación que deberán cumplir los proyectos
desarrollados para la Dirección General de Organización del Juego. Estas normas de
codificación serán chequeadas y validadas mediante las herramientas Sonar y Checkstyle.
4.1 Reglas de PMD
Las reglas de nivel 1 y 2 (errores) tendrán que ser necesariamente cumplidas en todos los
casos, no admitiéndose ninguna infracción salvo permiso expreso de la DGOJ.
Los incumplimientos de reglas de nivel 3 serán analizados por el equipo de Calidad, que
decidirá si están justificados o no.
Regla
IframeMissingSrcAttribute
Nivel
2
ReturnFromFinallyBlock
3
AvoidUsingOctalValues
3
Descripción
Escribir siempre el
elemento src en Iframes
Evitar el “return” desde
un bloque Finally
Al expresar valores
Ministerio de Hacienda y
Página 7 de 17
Administraciones Públicas
ConstructorCallsOverridableMethod
1
AccesorClassGeneration
1
EqualsNull
1
AssignmentToNonFinalStatic
2
CompareObjectsWithEqual
1
PositionLiteralFirstInComparisons
1
UnsynchronizedStaticDateFormatter
1
StringBufferInstantiationWithChar
1
NoHtmlComments
3
DuplicateJspImports
3
UseStringBufferForStringAppends
1
AvoidArrayLoops
1
decimales, no escribir
ceros precedentes, ya que
son tomados como
valores octales
Los constructores no
deben llamar a métodos
sobreescritos
No instanciar por medio
de constructores privados
desde fuera del
constructor de la clase, ya
que causa la generación
de un accesor
No usar equals() para
comparar con null
No asignar valores
variables inseguros a
campos estáticos
Comparar objetos con
equals(), no con ==.
Al hacer comparaciones
de cadenas, posicionar
siempre primero el literal
para evitar
NullPointerException
Sincronizar siempre
SimpleDateFormat a
nivel de método o bloque
Evitar instanciar
StringBuffer con un char,
ya que el char será
convertido a entero y
tomado por el constructor
como tamaño del
StringBuffer
No escribir comentarios
HTML. Los
comentarios JSP sí están
permitidos
Evitar sentencias import
duplicadas en JSPs
Usar StringBuffer y el
método append en lugar
de += para concatenar
cadenas
Usar System.arrayCopy
en lugar de copiar datos
entre dos arrays
Ministerio de Hacienda y
Página 8 de 17
Administraciones Públicas
UnnecesaryConversionTemporary
3
FinalFieldCouldBeStatic
3
CloseResource
3
InstantiationToGetClass
2
AvoidDuplicateLiterals
3
StringInstantiation
2
StringToString
2
InsufficientStringBuffer
3
EJBEntities
2
UnusedPrivateField
2
UnusedLocalVariable
2
UnusedPrivateMethod
2
UnusedFomalParameter
2
EmptyIfStmt
2
Evitar conversiones de
tipos innecesarias
Si un campo final es
asignado a una constante
en tiempo de
compilación, hacerlo
estático
Cerrar siempre los
recursos que lo requieran
(Connection,
Statement…)
No instanciar un objeto
para llamar a GetClass,
usar .class en su lugar
Evitar literales
duplicados, declarar el
String como campo
constante. Esta regla
estará justificada en
sentencias SQL.
No instanciar objetos
String a menos que sea
necesario
No llamar a .toString
desde un objeto String
Evitar en lo posible el
redimensionamiento de
StringBuffer, si se sabe el
tamaño del string
declararlo en el
constructor de
StringBuffer
No se recomienda el uso
de EJBs de entidad
No se permiten campos
privados declarados sin
usar
No se permiten variables
locales declaradas sin
usar
No se permiten métodos
privados declarados
sin usar
No se permiten
parámetros de métodos o
constructores que luego
no se utilicen
No se permiten sentencias
Ministerio de Hacienda y
Página 9 de 17
Administraciones Públicas
EmptyWhileStmt
2
EmptyCatchBlock, EmptyTryBlock,
EmptyFinallyBlock
2
EmptySwitchStatements
2
EmptySynchronizedBlock
2
EmptyStaticInitializer
2
UnconditionalIfStatements
2
EmptyStatementNotInLoop
2
MissingStaticMethodInNonInstatiatableClass
1
NoLongScripts
1
NoScriplets
2
OnlyOneReturn
3
SimplifyBooleanExpression
2
SwitchStmtsShouldHaveDefautl,
DefaultLabelNotLastInSwitchStmt
2
If sin contenido
No se permiten sentencias
While sin contenido. Para
bucles de temporización,
usar thread.Sleep
No se permiten bloques
Try, Catch ni Finally
vacíos
No se permiten sentencias
Switch vacías
No se permiten bloques
de sincronización vacíos
No se permiten
inicializadores estáticos
vacíos
No se permiten sentencias
If que siempre son
verdaderas o falsas
No se permiten sentencias
vacías (punto y coma solo
en una línea) excepto en
bucles
No se permiten clases sin
campos ni métodos
estáticos y con
constructor privado
Scripts de longitud mayor
de 10 líneas deberán
formar parte de Tag
Libraries y no páginas
JSP
Los Scriptlets deberían
estar organizados en Tag
Libreries o declaraciones
JSP, no ser parte de
páginas JSP
Sólo debe existir un único
punto de retorno de un
método (un return), y
debería ser la última
sentencia en el método
Evitar comparaciones
innecesarias en
expresiones booleanas
(sentencias complejas que
podrían simplificarse)
Las sentencias switch
siempre deben tener
Ministerio de Hacienda y
Página 10 de 17
Administraciones Públicas
NonCaseLabelInSwitchStatement
2
MissingBreakInSwitch
1
AvoidReassigningParameters
1
SwitchDensity
2
NonStaticInitializer
1
AvoidCallingFinalize
3
NoInlineStyleInformation
1
NoClassAtribute
1
NoJspForward
1
UseArrayListInsteadOfVector
2
AvoidThreadGroup
AvoidInstanceofChecksInCatchClause
2
4
PreserveStackTrace
2
implementado el caso
default, que debe ir
colocado en último lugar
No usar etiquetas no
relacionadas con switch
en sentencias switch
Debe haber al menos una
sentencia break en cada
sentencia case de switch
En los métodos, no
reasignar valores a los
parámetros
La densidad de sentencias
dentro de cada caso en un
switch no podrá exceder
de 10 líneas
No usar bloques de
código inicializadores
(que se ejecutan
previamente al
constructor)
Excepto autorización
expresa, no se podrá
utilizar el método
finalize() de los objetos
La información de estilo
estará contenida en
archivos CSS y no en
JSPs. Por tanto, no estará
permitido usar
expresiones del estilo
<B>, <FONT>…
No usar el atributo
“class” en las páginas
JSP, usar “styleclass”
para los estilos CSS
No redirigir desde
páginas JSP
No usar la colección
Vector, usar en su lugar
ArrayList
No usar ThreadGroup
Todos los tipos de
excepciones capturadas
deben ser manejadas con
su propia cláusula catch
Al disparar una excepción
Ministerio de Hacienda y
Página 11 de 17
Administraciones Públicas
AvoidCatchingThrowable
SignatureDeclareThrowException
1
1
ExceptionAsFlowControl
1
AvoidCatchingNPE,
AvoidThrowingNullPointerException
1
AvoidThrowingRawExceptionTypes
1
AvoidRethrowingException
1
NPathComplexity
2
ExcessiveMethodLength
3
ExcessiveParameterList
3
ExcessiveClassLength
3
CyclomaticComplexity
2
ExcessivePublicCount
3
desde un bloque catch,
pasar siempre la
excepción original a la
nueva para mantener el
stack trace
No usar Catch Throwable
No usar throws Exception
en la declaración de
método, usar una clase
derivada de
RuntimeException o una
excepción chequeada
No usar las excepciones
como control de flujo
No capturar excepciones
NullPointerException, ni
dispararlas
No disparar tipos de
errores o excepciones
primarias, en su lugar
lanzar subclases de ellas
No relanzar excepciones
desde bloques match
La complejidad NPath de
cada método debe ser
inferior a 300
El número máximo de
líneas permitidas por
método es 100
El número máximo de
parámetros permitidos en
un método es de 10
El tamaño máximo de un
archivo de clase es de
1000
La complejidad
ciclomática de cada
método deberá ser
inferior a 15
El número máximo de
métodos y atributos
públicos declarados en
una clase no podrá
exceder de 45
Tabla 1- Reglas de Codificación
Ministerio de Hacienda y
Página 12 de 17
Administraciones Públicas
4.2 Reglas de Checkstyle
Aparte de las reglas para chequear la existencia de Javadoc (explicadas en el apartado 3
Documentación del Código), se aplicarán una serie de reglas de Checkstyle para comprobar
que el código es mantenible.
En ningún caso se permitirá la existencia de incumplimientos de reglas de nivel Error. En los
casos de Warning, los incumplimientos serán evaluados individualmente por el
departamento de Calidad.
Las reglas aplicadas son:
Regla
AvoidInlineconditionals
AviodNestedBlocks
Nivel
Warning
Warning
BooleanExpression
Complexity
Warning
ClassDataAbstraction
Coupling
Warning
ClassFanOutComplexity
Warning
ConstantName
Error
DesignForExtension
Error
EmptyForInitializerPad
Error
EmptyForIteratorPad
Error
ExplicitInitialization
Error
FallThrough
Error
Descripción
No usar condicionales inline.
No se permiten bloques libres
en el código, por ejemplo int
whichIsWich = 0; { int
whichIsWhich = 2; }
El máximo de operadores
booleanos (&&, || y ^)
permitidos será de 4
El máximo de instancias de
otra clase en una clase dada
será de 10.
El número de clases en la que
una clase dada se apoye será
como máximo de 25.
Las constantes deberán ser
expresadas con todas las letras
en mayúsculas.
Las clases deberán ser
diseñadas para la herencia.
Seguir el principio de OOP:
open/close
Una sentencia “for” siempre
tendrá un valor inicial
Una sentencia “for‟ siempre
tendrá un valor sobre el que
itera
Cualquier clase o objeto
miembro debe estar
explícitamente inicializado al
valor por defecto de según su
tipo (nulo para referencias o
objetos, cero para numéricos y
char, y false para bolean).
Todas las sentencias de un
Ministerio de Hacienda y
Página 13 de 17
Administraciones Públicas
FinalStatic
Error
GenericIllegalRegexp
Error
HiddenField
Warning
IllegalCatch
Warning
IllegalImport
Error
IllegalTokenText
Error
IllegalType
Error
InnerAssignment
Error
switch deben tener su
sentencia de cierre (break,
return, throw o continue)
Todos los campos estáticos
deben declararse como “final‟
No se permiten las llamadas
de tipo:

System.out

System.in

System.err

System.exit
 ex.printStacktrace

Las variables locales y
parámetros de los métodos
deberán tener nombres
diferentes de los campos de la
clase a la que pertenecen.
No se permite hacer catch de
java.lang.Exception,
java.lang.Error o
java.lang.RuntimeException
No se podrán importar los
siguientes paquetes:
 Common-logging


No se permite utilizar las
cadenas:
 C:

SELECT *

LIKE
No se permite la definición de
tipos de la clase
java.sql.CallableStatement
No se pueden asignar
variables en subexpresiones,
por ejemplo String s =
Integer.toString(i = 2);
Ministerio de Hacienda y
Página 14 de 17
Administraciones Públicas
LocalHomeInterface
Warning
LocalInterface
Warning
MagicNumber
Error
MessageBean
Error
ModifiedControlVariable
Error
NestedTryDepth
Warning
OperatorWrap
Error
PackageDeclaration
Error
PackageHtml
Error
PackageName
Error
RemoteHomeInterface
Error
RemoteInterface
Error
SessionBean
Error
ThisParameter
Error
ThisReturn
Error
ThrowsCount
Warning
VisibilityModifier
Warning
Los métodos de una interfaz
local home cumplen los
requerimientos(*)
Los métodos locales no
pueden lanzar la excepción
java.rmi.RemoteException
Sólo se podrá escribir en
forma numérica el 0. El resto
de números deberán ser
declarados como constantes.
Los message beans cumplen
los requerimientos de clase (*)
No se pueden modificar las
variables de control de un
bucle dentro del bucle.
No se pueden anidar más de 2
bloques try-catch-finally.
Las sentencias con operadores
deben estar expresadas de
manera clara (paréntesis,
espacios…)
Los paquetes deben tener
declaración
Todos los paquetes deben
llevar documentación de
paquete (fichero
nombrepaquete.html para
acceder al javadoc)
Los paquetes deberán
llamarse de la forma
es.dgoj.nombrepaquete
Los métodos de una interfaz
remota home cumplen los
requerimientos(*)
Los métodos de una interfaz
remota cumplen los
requerimientos(*)
Los beans de sesión cumplen
los requerimientos de clase (*)
“this‟ no puede ser un
parámetro de métodos ni
constructores
“this‟ no puede ser un valor
de retorno
El máximo de sentencias
throw en un método es de 2
Sólo pueden ser públicos
miembros de tipo “static
Ministerio de Hacienda y
Página 15 de 17
Administraciones Públicas
final‟
Tabla 2- Reglas impuestas para la herramienta Checkstyle
(*) Para
más información de los requerimientos exigidos, consultar la web de Checkstyle (ver
http://checkstyle.sourceforge.net/config_j2ee.html).
5 Inyección de Dependencias
Para reducir de manera significativa el acoplamiento y sobre todo para poder generar
nuevas versiones de las dependencias sin tener que modificar las aplicaciones, se hará
hincapié en la aplicación del principio de inyección de dependencias para los atributos de
las clases en lugar de instanciarlos en los constructores o setters.
Para ello podrá utilizarse el framework de Spring o Weld (JSR-299: The new Java standard
for dependency injection and contextual lifecycle management).
6 Documentación del Código
El código fuente generado deberá estar debidamente documentado mediante Javadoc y
comentarios en el código, prestándose atención a los últimos, pues no se generan
mediante herramientas automáticas, pero son fundamentales para la correcta depuración
de error y mantenimiento del fuente.
Para chequear el contenido de Javadoc, se utilizará el plugin Checkstyle para Eclipse. Se
ejecutarán las siguientes comprobaciones de Checkstyle para confirmar la calidad de toda
la documentación Javadoc:
 PackageHtml: Comprueba que cada fichero java tiene su package.html
correspondiente.

JavadocType: Comprueba que todas las clases, interfaces etc tienen su Javadoc
correspondiente.

JavadocMethod: Comprueba que todos los métodos tienen su Javadoc
correspondiente. También se chequearán las excepciones.

JavadocVariable: Comprueba que todas las variables tienen su Javadoc
correspondiente.

JavadocStyle: Valida los comentarios Javadoc para asegurarse de que están bien
hechos (que no están vacíos, signos de puntuación correctos, etc.)
Ministerio de Hacienda y
Página 16 de 17
Administraciones Públicas
7 Duplicidad de Código
Se auditará el código de forma automática para asegurar que no haya código duplicado. La
herramienta a usar será el modulo CPD asociado con la librería PMD antes mencionada y
tomando como base mínima de duplicación 5 líneas de código fuente (75 tokens).
La existencia de bloques de código duplicado que superen este límite impuesto supondrá
un error que deberá ser solucionado para poder realizar la aceptación del código
entregado.
8 Visualización del Código
Para que el código sea fácilmente legible, las líneas no deben tener más de 80 caracteres
de longitud y un método de una clase no debe constar de más líneas que las que puedan
visualizarse en una pantalla (100 líneas).
Ministerio de Hacienda y
Página 17 de 17
Administraciones Públicas