Mini-Guía de Estilo de Programación

Mini-Guía de Estilo de Programación
En este documento vamos a ir recogiendo normas de estilo para que tanto el desarrollo
como la corrección del código sea más fácil y entendible por todos los componentes del
grupo. Este documento irá creciendo a medida que el proyecto Risk avance.
La forma en la que se va a presentar dichas normas será la siguiente:
- Cabecera con el nombre de la norma en negrita
- Breve explicación
- Ejemplo a modo de aclaración, si procede
Sin más dilaciones, comenzamos.
Comentarios: la forma en la que se incluirán los comentarios en el código es la
siguiente: utilizaremos la notación “/* comentario */”, con espacios en el comienzo y en
el final de los asteriscos, para todos los comentarios, tanto de una sola línea como de
varias. Para el caso en que el comentario explique lo que hace una función o método, se
usará la notación multilínea de Java, para que si que si se desea, se pueda generar el
javadoc del proyecto.
Es muy conveniente comentar el código para que el resto de compañeros pueda
entenderlo en caso de necesidad, pero tampoco hay que obsesionarse con ello. Con
aclarar un detalle que no se vea a simple vista o con resaltar algo interesante basta.
Para el caso en que se este comentando el funcionamiento de una función, hay sí que es
necesario un comentario extenso y que aclare el uso de dicha función.
Ejemplo:
/* esto es un comentario de una linea */
/* esto es un comentario de una linea
de varias lineas
*/
/*
* Este seria un comentario explicativo de una función
* que luego se vería en el javadoc
*/
Variables: para dar nombre a las variables utilizaremos la notación de letra capital en
mayúscula. Además, sobra decir que el nombre, aunque sea largo, debe identificar
claramente o lo más fiel posible, a lo que representa.
Ejemplo: protected int estoEsUnaVariable;
public boolean estoEsUnaVariableBandera = true;
Alineación de llaves y estructuración: para el uso de llaves que engloban código, se
realizará de la siguiente forma: la llave de comienzo ‘{’ irá en la línea inferior y no justo
después del nombre de la función. Además, si el código es demasiado largo y no se
visualiza entero en pantalla, se añadirá un comentario después de la llave final ‘}’
indicando a que corresponde.
Ejemplo:
public void funcionHolaMundo ()
{
.
.
.
if (<condición>)
{
…
}
else
{
…
}
.
.
.
} /*fin de funcionHolaMundo*/
Declaración de variables: las variables que se vayan a usar una sola vez o no tengan
una importancia vital para la implantación del código no hace falta declararlas justo
debajo de la cabecera de la función. Caso de por ejemplo contadores de bucle, variables
auxiliares, etc. Por el contrario, el resto de variables sí debe de definirse debajo de la
cabecera de la función.
“Get” y “Set” al principio del código: se trata que cuando creemos un método get o
set lo pongamos debajo de la declaración de variables del fichero .java donde lo estemos
haciendo, para que a continuación de todos los gets y set, puedan verse los otros
métodos más importantes.