Gua N 4

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: 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.JustificacinUsted 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 variabledouble ImpuestosIngreso;//Se entiende por s misma la utilidad de la variable

convenciones para nombrar variables y constantesVariables: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.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 mxima se puede representar as: TEMPERATURA_MAXIMAEvite 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;}

Ejemplo 2dia = (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

JustificationEstas 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

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 maysculaConsidere 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 comentariosLos comentarios proporcionan a los lectores con la informacin til para la comprensin de su programa.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 archivosLos 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.// ************************************************ *********

Uso de comentarios en una sola lneaUtilice 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 perodosumaDePuntajes = 0 ;for ( int i = 0; i < puntajes.length ;i ++ ){sumaDePuntajes = sumaDePuntajes + resultados [ i ];}

Media = float ( sumaDePuntajes ) / puntajes.length ;

Arrastrando ComentariosComentarios 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 auto-documentado.JustificacinLos 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 sumaa = float ( ss) / x ; // calcular la media de las puntuaciones

Nota:Este es un ejemplo de la manera EQUIVOCADA de comentar un programa

Formato del codigoEl 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.IdentacinLa 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.Ejemplopublic class HelloWorld{... public void greetUsuario (int horaActual)... {...... 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 blancoUse 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 comisinSimpleIO.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 cercanodoble 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 comisinSimpleIO.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 cercanodoble comisin = valorTotal * tasaComision;comisin = Math.round(comisin * 100) / 100.0;System.out.println ("Comisin : $" + comision);

Nota: Esta es la forma correcta

Longitud de lneaEvite 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 anteriorEjemplo: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 9