Gua N 4

Norman Salvador Aruz Lpez

Convenciones para la
nomenclatura: Normas y
directrices

INTRODUCCIN

Esta Gua de Estilo pone adelante los estndares de codificacin, convenciones y

directrices utilizadas para escribir cdigo correctamente y de alta calidad, adems de
facilitar la mantenibilidad del cdigo. Se basan en estndares de la industria, aunque
resumido a una forma simplificada para describir los conceptos. Siguiendo estos principios,
usted estar en mejores condiciones para producir cdigo que es correcto, requiere menos
esfuerzo de depuracin, y es ms fcil para los alumnos de seguir.

En el mundo real, las convenciones de cdigo son importantes para los programadores
para una serie de razones:

80% del coste de vida til de una pieza de software va a mantenimiento. Cualquier
software Apenas se mantiene durante toda su vida por el autor original. Convenciones
Cdigo mejorar la legibilidad del software, permitiendo a los ingenieros de software a
entender nuevo cdigo de forma ms rpida y completamente.
Normas de codificacin permiten a los equipos de programadores a entender ms
fcilmente cada cdigo de los dems y ayudar a errores puntuales. En lugar de
codificar a partir de cero, los miembros del equipo tienen ms posibilidades de
compartir y reutilizar cdigo cuando las convenciones de estilo y comentando entre los
miembros del equipo son los mismos.

Entre las razones para cualquier equipo de desarrollo se encuentran:

Es importante aprender prcticas de codificacin correctos desde el principio en lugar

de adoptar hbitos de codificacin malas que tendr que ser corregido por el camino.
El cuidado en seguir las convenciones de codificacin reducir el nmero de errores
lgicos en el cdigo, as como reducir el tiempo de depuracin requerido para arreglar
sus errores lgicos restantes.
Su cdigo es ledo por los alumnos de TA y el instructor. Ellos tendrn un tiempo ms
fcil la comprensin de la lgica de su cdigo y ayudar a depurar los errores si todos
siguen un conjunto coherente de normas.

CONVENCIONES DE NOMENCLATURAS

Las siguientes pautas generales se aplican a la eleccin de los nombres de

identificadores en sus programas:

Pgina 1

Utilice las descripciones completas para los nombres. Evite el uso de abreviaturas. Por
ejemplo, usar nombres como nombre, apellido, y MiddleInitial en lugar de las
versiones ms cortas fName, lname, y mi.
Evite nombres excesivamente largos (ms de 15 caracteres). Por ejemplo,
setTheLengthField debera acortarse a setLength.
Evite los nombres que son muy similares o difieren slo por si acaso. Por ejemplo,
evitar el uso de los nombres de productos, los productos y los productos en el mismo
programa por temor a mezclarlos.

Justificacin
Usted debe escribir el cdigo con el objetivo de hacer comprensible a los dems. Otros
tendrn que leer y entender el cdigo y una de las principales claves para la comprensin
es a travs de la utilizacin de nombres de identificadores significativos.

Mediante el uso de nombres significativos, usted va un largo camino hacia la escritura de

cdigo auto-documentado. Es decir, el cdigo que es comprensible por s mismo sin
necesidad de comentarios adjuntos. Por ejemplo, observe el siguiente segmento de cdigo
y determinar por s mismo que los nombres de las variables ImpuestosVenta y
ImpuestosIngreso son preferibles a Impuestos1 y Impuestos2 porque los nombres son
auto documentados, es decir se entienden por s mismos.
double impuesto1; //Tasa de impuesto sobre la venta (ejemplo de un mal nombre
para una variable)
double impuesto2; //Tasa de impuesto sobre el ingreso (ejemplo de un mal nombre
para una variable)
double ImpuestosVenta; // No requiere comentarios que describan la utilidad de la
variable
double ImpuestosIngreso;//Se entiende por s misma la utilidad de la variable

CONVENCIONES PARA NOMBRAR VARIABLES Y CONSTANTES

Variables:
Elegir nombres significativos que describen para lo que la variable se utiliza. Evite los
nombres genricos como nmero o temp (temporal) cuyo propsito es claro.
Componer nombres de variables usando letras maysculas y minsculas combinadas que
comienzan con una letra minscula (notacin Camell Case). Por ejemplo, utilice
ordenVenta lugar de OrdenVenta u orden_venta.
Utilice nombres en plural para las matrices. Por ejemplo, utilice PuntuacionesPruebas
lugar de PuntuacionPrueba.
Pgina 2

Excepcin: para las variables de control del bucle se nombran a menudo simplemente i, j,
k, declararlo local para el bucle siempre y cuando sea posible.
Declarando y comentando las variables locales

Declarar cada variable local en su propia lnea de cdigo. No variables de grupo,

separados por comas como un atajo a declarar cada uno en su propia lnea.
Si el significado y el uso de la variable no es clara, aadir un comentario lnea de fondo
(//) que indica lo que la variable se utiliza y por qu. Sin embargo, una solucin mejor
es elegir un nombre significativo para evitar la necesidad de que el comentario lnea de
fondo.
Siempre que sea posible, inicializar la variable con su valor inicial en la sentencia de
declaracin.

Constantes:
Las constantes se nombran utilizando letras maysculas en todo el nombre de la variable,
utilizando un guion bajo en las palabras compuestas. Por ejemplo:
La
constante
Temperatura
TEMPERATURA_MAXIMA

mxima

se

puede

representar

as:

Evite el uso de nmeros mgicos en el cdigo. Nmeros mgicos son nmeros reales como
27 que aparecen en el cdigo que requiere el lector de averiguar lo que 27 se est
utilizando para. Considere el uso de constantes con nombre para cualquier nmero distinto
de 0 y 1.

Justificacin:
Mediante el uso de todo en maysculas para sus constantes con nombre, otros leyendo su
cdigo sabrn inmediatamente que el identificador es un valor constante fijo que no se
puede cambiar.

El uso de nombres significativos para las constantes en lugar de utilizar nmeros mgicos
en el cdigo hace que el cdigo auto-documentado, lo que reduce la necesidad de los
comentarios finales. Por ejemplo, mira a las dos lneas de cdigo a continuacin y
determinar por s mismo que el uso de constantes con nombre hace segunda lnea de
cdigo auto-documentado y ms legible.

Ejemplo 1:
for (int i = 0; i < TEMPERATURA_MAXIMA; i++)
{
Temperatura = Temperatura + 1;
Pgina 3

}
Ejemplo 2
dia = (3 + numeroDeDias) % 7; //No usar nmeros mgicos!
final int MIERCOLES = 3;
final int DIAS_EN_SEMANA = 7
dia = (MIERCOLES + numeroDeDias) % DIAS_EN_SEMANA; //Este si, se entiende por s
sola
Justification
Estas convenciones son una prctica comn en la comunidad de desarrollo de Java, as
como la convencin de nombres para las variables utilizadas por Sun Microsistems
(adquirida por Oracle en 2010) para los paquetes principales de Java. Escribir cdigo que
sigue a estas convenciones hace que las variables sean fcil de distinguir para otros.
CONVENCIONES PARA NOMBRAR MTODOS (FUNCIONES)

Trate de llegar a los nombres de mtodos significativas que describen de manera sucinta el
propsito del mtodo, por lo que su cdigo de auto-documentado y reduciendo la
necesidad de comentarios adicionales.

Componer nombres de los mtodos usando letras maysculas y minsculas

combinadas, comenzando con una letra minscula y comenzando cada palabra
subsiguiente con una letra mayscula.
Comience nombres de los mtodos con un fuerte verbo de accin (por ejemplo,
depsito). Si el verbo no es lo suficientemente descriptivo por s mismo, incluir un
sustantivo (por ejemplo, agregarInteres). Aadir adjetivos si es necesario aclarar el
sustantivo (por ejemplo, convertirEuroDolares).
Utilice los prefijos cambian y leen para los mtodos get y set. Los mtodos Getter
simplemente devuelven el valor de una variable de instancia; mtodo setter cambiar el
valor de una variable de instancia. Por ejemplo, utilice los nombres de los mtodos
getBalance y setBalance para acceder o cambiar la instancia equilibrio variable.
Si el mtodo devuelve un valor booleano, el uso es o tiene como prefijo para el nombre
del mtodo. Por ejemplo, utilice esPar o tieneCredito para los mtodos que devuelven
valores verdaderos o falsos. Evite el uso de la palabra No en el nombre del mtodo
booleano, utilice el ! operador en su lugar.

Por ejemplo, usar if (!esPar) lugar de noEsPar

Pgina 4

Justificacin:
Estas convenciones son una prctica comn en la comunidad de desarrollo de Java, as
como la convencin de nombres para los mtodos utilizados por Oracle para los paquetes
principales de Java. Escribir cdigo que sigue a estas convenciones hace que los mtodos
fciles para que otros lo identifican en el cdigo. A pesar de que las variables y los
mtodos de ambos comienzan con una letra minscula seguida de maysculas y
minsculas, que fcilmente pueden ser diferenciados unos de otros porque los nombres de
mtodos comienzan con un verbo y se siguen inmediatamente con un conjunto de
parntesis , por ejemplo : moverCuenta().

CONVENCIONES PARA NOMBRAR PARAMETROS EN LOS METODOS (FUNCIONES)

Con nombres de los parmetros formales, seguir las mismas convenciones de

nomenclatura como con variables, es decir, usar maysculas y minsculas, comenzar con
una letra minscula, y comenzar cada palabra subsiguiente con una letra mayscula
Considere usar el prefijo de un o una con nombres de parmetros. Esto ayuda a que el
parmetro distinguible de variables locales y de instancia.
De vez en cuando, con los mtodos de uso muy generales, los nombres elegidos pueden
ser bastante genrico (por ejemplo, aNumero). Sin embargo, la mayora de las veces los
nombres de los parmetros deben describir sucintamente el tipo de valor que se pasa en el
mtodo.
Ejemplo:
public void deposit(long unNumeroCuenta, double unDeposito)
{
...
}
public boolean esNumero (int unValor)
{
...
}

CONVENCIONES PARA USO DE LOS COMENTARIOS

Los comentarios proporcionan a los lectores con la informacin til para la comprensin de
su programa.

Pgina 5

Utilice los comentarios para proporcionar una visin general o resmenes de los trozos de
cdigo y proporcionar informacin adicional que no est fcilmente disponible en el propio
cdigo.
Comentario de los detalles de las decisiones de diseo obvias no triviales o no; evitar los
comentarios que se limita a reiterar la informacin que est presente y claro en la lectura
del cdigo.
Se utilizarn tres tipos de comentarios:

Cabecera del archivo: comenta el suministro de informacin de identificacin sobre

el programa y el autor.
Lnea por lnea: comenta que proporciona una visin general o resmenes de los
trozos de cdigo.
Comentarios finales: que proporcionan informacin para una lnea de cdigo.

Evitar el exceso de comentar su cdigo. La frecuencia de los comentarios a veces refleja la

mala calidad del cdigo. Cuando usted se siente obligado a agregar un comentario,
considere volver a escribir el cdigo para hacerlo ms claro.
Adems, los comentarios de estilo C / * ... * / pueden usarse temporalmente para
comentando bloques de cdigo durante la depuracin. Programas presentados para optar
a un grado acadmico no deben tener bloques de cdigo como comentario.
Comentarios en la cabecera de los archivos
Los comentarios de cabecera del archivo proporcionan lectores la informacin que
necesitan para encontrar su proyecto en la red, identificar el autor del programa, as como
de recopilar estadsticas sobre la dificultad del proyecto en base a las horas requeridas
para completar el programa.
Plazos de ejecucin se recogen para todos los programas presentados y de la media
calculada para la clase. Puede redondear las horas trabajadas a la hora ms cercana.
Dibujo: en tiempos de finalizacin son aceptables; En general se espera que la mayora de
las tareas de programacin tendr un promedio de alrededor de cuatro horas de esfuerzo.
Ejemplo
//
//
//
//
//
//
//
//
//
//
//
//
//

************************************************ **********
Asignacin: Programa 2
Cuenta : (Ingrese su nmero de cuenta aqu)
Autor : ( Escriba su nombre completo aqu)
Tiempo de ejecucin :( Escriba el nmero total de horas que
Gastado en la asignacin )
Cdigo de Honor : Prometo que este programa representa mi propia
Cdigo del programa. Recib ayuda de ( escriba los nombres de
Otros que ayudaron con la asignacin , escriben nadie si
Recibi ninguna ayuda) en el diseo y la depuracin de mi programa.

Pgina 6

// ************************************************ *********
Uso de comentarios en una sola lnea
Utilice los comentarios de una sola lnea, tambin llamados comentarios en lnea, para
proporcionar breves comentarios de resumen para trozos de cdigo.
Proceda comentarios de una sola lnea con una lnea en blanco y alinear el comentario con
el cdigo resume. No sienta la necesidad de comentar cada lnea de cdigo, en lugar
resumir trozos de cdigo entre 3 a 7 lneas de longitud.
Comience comentarios de una lnea con una doble barra (//) que le dice al compilador que
ignorar el resto de la lnea. Nota: no coloque ningn carcter entre las dos barras.
Justificacin:
Al separar trozos de cdigo por lneas en blanco y procediendo cada una con un
comentario explicativo, los lectores (y usted mismo) pueden identificar rpidamente y
comprender secciones de cdigo en la que se llevan a cabo acciones especficas.
Siempre agregar comentarios mientras usted est codificando en lugar de esperar hasta
que se termine el programa. Los resmenes y las razones sern fresca y precisa en lugar
de lugar- rellenos que no ofrecen ningn valor real.
Ejemplo
//Calcular la puntuacin media del examen para el examen de mitad de perodo
sumaDePuntajes = 0 ;
for ( int i = 0; i < puntajes.length ;i ++ )
{
sumaDePuntajes = sumaDePuntajes + resultados [ i ];
}
Media = float ( sumaDePuntajes ) / puntajes.length ;

Arrastrando Comentarios
Comentarios lnea por lnea se utilizan para proporcionar una explicacin para una sola
lnea de cdigo. Comience comentarios finales con una doble barra ( // ) y colocarlos a la
derecha de la lnea de cdigo que hacen referencia.
Comentarios finales se utilizan para explicar cdigo complicado, especifique lo abrevian los
nombres de variables se refieren a, o de otra manera aclaran lneas poco claras de cdigo.
En general, evite el uso de comentarios finales. En lugar reescribir cdigo complicado o
poco clara, utilizar nombres de variables significativas, y se esfuerzan por cdigo autodocumentado.
Pgina 7

Justificacin
Los comentarios finales se utilizaban a los das de programacin en lenguaje ensamblador
donde eran imposibles de entender sin el uso de los comentarios de las lneas individuales
de cdigo.
Lenguajes de programacin modernos como Java permiten a los programadores escribir
cdigo auto-documentado el uso de nombres de variables significativas, lo que elimina la
necesidad de que los comentarios finales.
ss = s1 + s2 + s3 ; // aadir las tres puntuaciones en la suma
a = float ( ss) / x ; // calcular la media de las puntuaciones
Nota:
Este es un ejemplo de la manera EQUIVOCADA de comentar un programa
FORMATO DEL CODIGO

El Formato se refiere a la sangra, la alineacin y el uso de espacio en blanco para disear

su programa para aumentar la legibilidad para otros.
La consistencia es la clave para producir un cdigo legible. Si bien muchos pueden
argumentar a mritos de 3 contra 4 espacios de sangra, la colocacin de llaves, etc., la
verdadera clave es adoptar un estilo de formato y mantener a la misma.
En el mundo real, las organizaciones de la adopcin de un estndar para dar formato a
aumentar la productividad del programador, reduciendo las variaciones y las decisiones
triviales entre los equipos de programadores. Siguiendo las normas de formato, los
programadores no tienen que decidir individualmente sobre los asuntos relativamente
triviales de formato. En su lugar, pueden pasar su tiempo y energa en los problemas ms
difciles de la solucin de programa.
Identacin
La mayora de los programadores estandarizar en 2, 3, o 4 espacios de sangra. Tres
espacios funciona bien: todava es notable incluso con los tamaos de fuente ms
pequeos utilizados para imprimir pero no tan grande que ajuste de lnea se convierte en
una preocupacin importante.
Si bien puede parecer ms fcil de insertar las fichas en lugar de espacios para la
identacion, las pestaas se establecen de manera incompatible con otros ordenadores y lo
que puede parecer perfecto en su equipo puede aparecer escalonados en la computadora
de otra persona si sus ajustes de la ficha no coinciden con el suyo propio.
Ejemplo
public class HelloWorld
{
... public void greetUsuario (int horaActual)
Pgina 8

... {
...... System.out.print ("bueno");
...... if ( horaActual < Tarde )
...... {
......... System.out.println ("Maana");
...... }
...... else if (horaActual < Tarde)
...... {
......... System.out.println ("Tarde");
...... }
...... else
...... {
......... System.out.println("Noche");
...... }
...}
}
Nota: El carcter . Denota la identacin
Espacios en blanco
Use lneas en blanco y los espacios en blanco para mejorar la legibilidad del cdigo.
Use lneas en blanco para separar trozos de cdigo del programa. Trozos son grupos
lgicos de sentencias de programa (generalmente 3 a 7 lneas de longitud) y por lo general
procedido con un resumen comentario de una sola lnea. Utilice una lnea en blanco antes
de cada trozo programa. Use dos lneas en blanco antes del inicio de cada nuevo mtodo
dentro de una clase.
Utilice un espacio en blanco en ambos lados de smbolos de operador, despus de las
comas en las listas de argumentos, y despus de un punto y coma en las declaraciones.
Lneas y espacios en blanco permiten al programador para mostrar prrafos u organizacin
del cdigo en pequeas agrupaciones, lgicas para mejorar la legibilidad. Mira las dos
ejemplos a continuacin y observe cunto ms legible se compara el ejemplo inferior al
ejemplo superior sin lneas en blanco y espaciado.
Ejemplo:
Fragmento de cdigo sin espacios
// Pide al usuario que introduzca el tipo de comisin
SimpleIO.prompt( " Ingrese el tipo de comisin (en porcentaje ) :");
entradaUsuario=SimpleIO.readLine ();
doble tasaComision=Double.parseDouble ( entradaUsuario )/100;
// Calcular y mostrar la comisin, el redondeo al cntimo ms cercano
doble comision=valorTotal*tasaComision;
comision=Math.round(comision*100)/100.0 ;
System.out.println ("Comisin : $" + comision) ;
Nota: Esta es la forma no deseada
FRAGMENTO DE CDIGO CON ESPACIOS
// PIDE AL USUARIO QUE INTRODUZCA EL TIPO DE COMISIN
Pgina 9

SIMPLEIO.PROMPT( "INGRESE EL TIPO DE COMISIN (EN PORCENTAJE ) :");

ENTRADAUSUARIO = SIMPLEIO.READLINE ();
DOBLE TASACOMISION = DOUBLE.PARSEDOUBLE ( ENTRADAUSUARIO ) / 100;
// CALCULAR Y MOSTRAR LA COMISIN, EL REDONDEO AL CNTIMO MS CERCANO
DOBLE COMISIN = VALORTOTAL * TASACOMISION;
COMISIN = MATH.ROUND(COMISIN * 100) / 100.0;
SYSTEM.OUT.PRINTLN ("COMISIN : $" + COMISION);
NOTA: ESTA ES LA FORMA CORRECTA

Longitud de lnea
Evite las lneas de ms de 80 caracteres. Cuando una expresin no cabe en una sola lnea
de 80 caracteres, romperlo acuerdo con estos principios generales:

Romper despus de una coma.

Romper antes de un operador.
Alinear la nueva lnea con el principio de la expresin en el mismo nivel en la lnea
anterior

Ejemplo:

algunMetodo(expresionLarga1, expresionLarga2, expresionLarga3,

expresionLarga4, expresionLarga5);
nombreLargo1 = nombreLargo2 * (nombreLargo3 + nombreLargo4 - nombreLargo5)
+ 4 * nombreLargo6;
Las lneas de ms de 80 personajes envuelven en la impresin del cdigo fuente, haciendo
que su cdigo sea ms difcil de leer y entender.

Referencias

Washingtong, U. C. (2015). Convenios Cdigo de Sun para el lenguaje de programacin Java .

Obtenido de Universidad Central de Washingtong:
http://www.cwu.edu/~gellenbe/javastyle/index.html

Pgina 10