martes, octubre 26, 2010

Guía de estilo de JAVA

A continuación se transcribe, desde la página del curso Curso práctica en ingeniería de software publicado por el Instituto Tecnológico de Massachussets (MIT) en su iniciativa de cursos libres OpenCourseWare  traducidos a su vez al español por el portal Universia, una guía de estilo para programar en java:




Boletín S1: Guía de estilo de Java™

Visión global

El estilo del código constituye una parte crucial en el ejercicio de la buena ingeniería del software. El objetivo se centra en escribir código que sea claro y fácil de entender, y que al mismo tiempo reduzca el esfuerzo que se emplea en hacer ampliaciones o modificaciones futuras.
Hay varios aspectos del código que lo pueden hacer más legible. Algunos de los más importantesson el empleo de nombres descriptivos, así como el uso de una indentación coherente y decomentarios informativos.
En el curso 6.170 no le indicamos que siga un estilo de código detallado. No obstante, esperamos que su código sea claro y fácil de entender. Este boletín le facilita una serie de directrices generales dentro de las cuales usted debería desarrollar un estilo de código propio y logrado.

Nombres descriptivos

Debería usar nombres nemónicos para los paquetes, los tipos, las variables y las etiquetas de ramificación, mediante los cuales se pudiese vislumbrar su uso y/o significado. Esto no significa que
los nombres tengan que ser muy largos. Por ejemplo, nombres como i y j servirían para nombrar los índices de bucles cortos, ya que los programadores conocen por convención los significados y usos de estas variables.

Le aconsejamos que siga una convención común que consiste en poner en mayúsculas los nombres
de las clases y en empezar los nombres de las variables y de los paquetes con letra minúscula. Existen otras convenciones comunes tales como escribir el nombre completo de las constantes en mayúsculas; no le pediremos que siga ninguna convención en concreto, pero debería elegir aquellas que le resultaran útiles y seguirlas de manera coherente.

Indentación coherente

Una indentación coherente del código ayuda al lector a comprender la estructura lógica de mismo,
al facilitarle la tarea de ver dónde acaban las sentencias if y los bucles while, etc. 
Debería hacer uso de estrategias coherentes; por ejemplo, sea coherente en cuanto a si pone el corchete en la misma línea que el if o en la línea siguiente, o en cuanto a la apariencia de sus bloques try-catch-finally.Examine el código del libro de texto para observar una muestra de estilo; puede desarrollar su propio código con total libertad si le resulta más cómodo.
Emacs proporciona un modo autoindent, que activa la indentación automática. Debería utilizarlo para dar formato a su código al mismo tiempo que lo escribe y volver a darle formato después de
realizar alguna modificación. También puede usar grind para dar a su código un formato decente para la impresión, incluso si el fichero fuente no está bien indentado.

Comentarios informativos

No cometa el error de escribir comentarios por todas partes --un comentario malo o inútil es peor que no poner nada. Si la información está clara en el código, el añadir un comentario simplemente supondrá trabajo de más para el lector.
    i++;    // se incrementa i     ESTE COMENTARIO ES INÚTIL
Los buenos comentarios añaden información al código de manera clara y concisa. Por ejemplo, los comentarios son informativos si:
  • Permiten que el lector evite leer el alguna parte del código: el siguiente comentario ahorra al lector el esfuerzo de tener que averiguar el efecto de algunas fórmulas complicadas, y pone de manifiesto la intención del programador, de manera que las fórmulas se puedan revisar más tarde.
    // calcula la desviación estándar de los elementos de la lista que son 
    // menores que el valor límite
    
    for (int i=0; i<n; i++) {
    
        //...
    
    }
    Una aplicación importante de este tipo de comentario consiste en documentar los argumentos y los valores que devuelven las funciones, de modo que los clientes no tengan que leer la implementación para comprender cómo usar la función.
     
  • Explican un algoritmo o paso oscuro: esto es particularmente importante cuando los resultados
    de algún paso no quedan claros en ese trozo de código. Debería explicar algoritmos que puedan resultar engañosos, operaciones con efectos secundarios, números mágicos del código, etc.
    // Señal de que una nueva petición de transferencia se ha completado y está lista
    // para ser procesada. El hilo principal comenzará la transferencia del disco
    // la próxima vez que despierte y se dé cuenta de que esta variable ha cambiado.
    
    buffer_manager.active_requests ++;
  • Indican supuestos: ¿bajo qué supuestos funciona adecuadamente una parte del código?
    // La memoria intermedia (buffer) contiene al menos un caracter.
    // Si la memoria intermedia está vacía, el gestor de interrupciones vuelve sin
    
    // llamar a esta función.
    
    c = buffer.get_next_character();
  • Señalan deficiencias del código y partes de código incompleto: es habitual que la primera versión del código no esté completa; es importante señalar el código que se sabe que es incorrecto. Si se le agota el tiempo de entrega de un ejercicio y presenta un programa que no funciona correctamente en todas las entradas, esperamos que su código muestre que usted es consciente de esas deficiencias.
    if (n > 0) {
    
        average = sum / n;
    
    } else {
    
        // XXX necesita utilizar el promedio de decaimiento de la  iteración anterior.
        // Por ahora, use simplemente un valor arbitrario. 
        average = 15;
    
    }
Consejos:
  • No escriba primero el código para luego comentarlo; coméntelo sobre la marcha. Es poco probable que pueda volver y hacerlo más tarde.
  • No le exigiremos que escriba comentarios en cada objeto del programa como se hace en algunos cursos de ingeniería del software. Sin embargo, su nota dependerá considerablemente de la claridad del código y puede que alguna parte del programa que esté clara para usted, no resulte tan clara para el lector. Por lo tanto, le conviene añadir comentarios aclaratorios a todas las clases, campos y métodos.

1 comentarios:

Jose Ramon Santana Vazquez dijo...

...traigo
sangre
de
la
tarde
herida
en
la
mano
y
una
vela
de
mi
corazón
para
invitarte
y
darte
este
alma
que
viene
para
compartir
contigo
tu
bello
blog
con
un
ramillete
de
oro
y
claveles
dentro...


desde mis
HORAS ROTAS
Y AULA DE PAZ


TE SIGO TU BLOG




CON saludos de la luna al
reflejarse en el mar de la
poesía...


AFECTUOSAMENTE
JORGE

ESPERO SEAN DE VUESTRO AGRADO EL POST POETIZADO DE CUMBRES BORRASCOSAS, ENEMIGO A LAS PUERTAS, CACHORRO, FANTASMA DE LA OPERA, BLADE RUUNER Y CHOCOLATE.

José
Ramón...

Publicar un comentario

LinkWithin

Related Posts Plugin for WordPress, Blogger...

Calificar