Carmen.

Estndares de codicacin
Manuel Arias Calleja

II

ndice general
1. Estandares de codicacin 1.1. Nombres de cheros . . . . . . . . . . . . . . . 1.2. Organizacin de cheros . . . . . . . . . . . . . 1.2.1. Ficheros de cdigo fuente . . . . . . . . 1.3. Indentacin . . . . . . . . . . . . . . . . . . . . 1.3.1. Lineas largas . . . . . . . . . . . . . . . 1.4. Comentarios . . . . . . . . . . . . . . . . . . . . 1.4.1. Comentarios de implementacin . . . . . 1.4.2. Comentarios de documentacin . . . . . 1.5. Declaraciones . . . . . . . . . . . . . . . . . . . 1.5.1. Nmero de declaraciones por lnea . . . . 1.5.2. Inicializacin . . . . . . . . . . . . . . . 1.5.3. Localizacin . . . . . . . . . . . . . . . 1.5.4. Declaraciones de clases e interfaces . . . 1.6. Sentencias . . . . . . . . . . . . . . . . . . . . . 1.6.1. Sentencias simples . . . . . . . . . . . . 1.6.2. Sentencias compuestas . . . . . . . . . . 1.6.3. Ejemplos: Sentencias if, for, while, do ... try ... catch . . . . . . . . . . . . . . . . 1.6.4. Sentencias de retorno . . . . . . . . . . . 1.7. Espacio en blanco . . . . . . . . . . . . . . . . . 1.7.1. Lneas en blanco . . . . . . . . . . . . . 1.7.2. Caracteres de espacio . . . . . . . . . . . 1.8. Asignacin de nombres . . . . . . . . . . . . . . 1 1 1 1 2 2 3 3 3 4 4 4 4 5 5 5 5 5 7 8 8 8 8

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . while, switch y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

III

IV

Captulo 1

Estandares de codicacin
Se denen estndares de codicacin porque un estilo de programacin homogeneo en un proyecto permite que todos los participantes lo puedan entender en menos tiempo y que el cdigo en consecuencia sea mantenible. Directiva 1 Puede ser que el estandar de documentacin denido no sea perfecto para todas las situaciones. Si esto es as y cree que debe salirse de la norma: Documente los motivos

1.1.

Nombres de cheros
Cdigo fuente: .java Cdigo compilado: .class

Sujos de cheros en Java1 :

Nombres de cheros comunes: README: Resumen de informacin importante relativa al directorio en el que est ubicado

1.2.

Organizacin de cheros

Un chero consta de secciones separadas por lneas en blanco y lneas de comentario, ningn chero debe tener ms de 2000 lneas de cdigo

1.2.1. Ficheros de cdigo fuente

Cada chero contiene una nica clase o interface. Si hay una clase privada o una interfaz asociadas a una clase pblica se puede poner en el mismo chero. La clase pblica debe ser la primera.
1

Segn las convenciones de cdicacin de Sun

Ordenacin de las secciones en un chero de cdigo fuente Estas secciones deben ir separadas por una lnea en blanco Sentencia: package xxx.yyy; Sentencias de importacin. Ej: import java.util.ArrayList;. No hay lneas en blanco entre ellas Cdigo de la clase. Va precedido por comentarios tipo javadoc con la siguiente informacin: Prlogo explicativo de la clase (opcional),autor, versin, referencias a otros elementos de codigo si se considera que debe haberlas

1.3. Indentacin
La unidad de indentacin de bloques de sentencias son 4 espacios

1.3.1. Lineas largas

Cuando una lnea no quepa en una nica lne se debe fraccionar atendiendo a estos principios generales Fraccionar despus de una coma Fraccionar despus de un operador Es mejor romper unidades de alto nivel que de bajo nivel. Ejemplo: longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // Mejor longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // Peor Si las reglas anteriores producen cdigo confuso utilizar indentacin de 8 caracteres. Ejemplo: // NO USAR ESTA INDENTACION if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); // SE CONFUNDE CON LAS ANTERIORES } // USAR ESTA INDENTACION if ((condition1 && condition2) || (condition3 && condition4) 2

||!(condition5 && condition6)) { doSomethingAboutIt(); } // O ESTA if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); }

1.4.

Comentarios

Normas generales a seguir en toda documentacin: 1. Los comentarios deben aadir claridad al cdigo. Deben contar el por qu y no el cmo. 2. Deben ser concisos. 3. Idealmente hay que escribir la documentacin antes que el cdigo. Hay dos tipos de comentarios: Comentarios de implementacin y comentarios de documentacin. Los comentarios de implementacin son del tipo: // ... o /* ... */. Los comentarios de documentacin son del tipo: /** ... */. Los comentarios de implementacin describen el cdigo, los de documentacin una visin de ms alto nivel para gente que no tiene el cdigo a mano y que slo quiere usarlo. La informacin de los comentarios no debe ser evidente, deben ser cosas que no estn contenidas en el codigo Los comentarios no deben estar en cajas dibujadas con asteriscos o similar ni deben incluir caracteres extraos

1.4.1.

Comentarios de implementacin

Comentarios de bloque: Al comienzo de cada chero o bloque. No se usan en este proyecto Comentarios de linea: Son comentarios explicativos de una parte pequea del cdigo. Sintaxis: // ... o /* ... */

1.4.2. Comentarios de documentacin

Son los comentarios destinados a ser procesados por javadoc. Se puede ver informacin adicional sobre javadoc en: http://java.sun.com/products/jdk/javadoc/writingdoccomments.html http://java.sun.com/products/jdk/javadoc/ Importante: No se pueden usar comentarios de documentacin para bloques de cdigo dentro de mtodos porque javadoc los asigna a la primera declaracin que encuentre detrs de ellos 3

La indentacin correcta segn Sun es: /** * Comentario sobre la clase A */ public class A { ... } Otras normas que se siguen en el proyecto son: No se documentar lo que sea evidente Siempre se usarn los tags de javadoc para documentar los parmetros y valores de retorno, aunque slo sea para poner su nombre

1.5. Declaraciones
1.5.1. Nmero de declaraciones por lnea
Se debe declarar cada variable en una lnea distinta, de esta forma cada variable se puede comentar por separado. Ejemplo: int level, size; // Mal int level; // Indentation level int size; // Size of table Los arrays se deben declarar de este modo: double[] table; // Bien double []table; // Mal

1.5.2. Inicializacin
Inicializar cada variable en su declaracin a menos que su valor inicial dependa de algn clculo

1.5.3. Localizacin
En el comienzo de los bloques. La nica excepcin es el bucle for. No se deben declarar variables con el mismo nombre que otras en un mtodo 4

1.5.4.

Declaraciones de clases e interfaces

Se siguen estas reglas: No hay espacio entre el nombre del mtodo, el parntesis y la lista de parmetros Se abre la llave { al nal de la misma lnea que la declaracin La llave de } debe aparecer en lnea aparte con la misma indentacin que el mtodo o clase que cierra

1.6.
1.6.1.

Sentencias
Sentencias simples

Cada lnea debe contener una sola sentencia. Ejemplos argv++; // Bien argc++; // Bien argv++; argc++; // Mal

1.6.2.

Sentencias compuestas

Son las que estn entre llaves { y } Deben estar indentadas a un nivel superior que el precedente Todas las sentencias del tipo if o for, while, do ... while debern tener llaves aunque slo contengan una sentencia, de esta forma se evita la introduccin accidental de errores si se aaden posteriormente sentencias

1.6.3.

Ejemplos: Sentencias if, for, while, do ... while, switch y try ... catch

Sentencia if if (condition) { statements; } if (condition) { statements; } else { statements; 5

} if ( condition) { statements; } else if (condition) { statements; } else { statements; } Sentencia for y su nueva versin for ( initialization; condition; update) { statements; } for ( initialization; condition; update); La nueva versin del for tiene el siguiente formato for (Declaration : List) { statements; } Ejemplo. Antes: void cancelAll(Collection c) { for (Iterator i = c.iterator(); i.hasNext(); ) { TimerTask tt = (TimerTask) i.next(); tt.cancel(); } } Despus: void cancelAll(Collection c) { for (Object o : c) { ((TimerTask)o).cancel(); } } Sentencia while: while (condition) { statements; } while (condition); 6

Sentencia do-while: do { statements; } while ( condition); La sentencia switch tiene este formato e indentacin switch ( condition) { case ABC: statements; /* El comentario tambien indentado */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; } La sentencia try ... catch try { statements; } catch (ExceptionClass e) { statements; } Si est seguida por nally: try { statements; } catch (ExceptionClass e) { statements; } finally { statements; }

1.6.4.

Sentencias de retorno

No se pondr la expresin de retorno entre parntesis a menos que con ello se gane en claridad 7

1.7. Espacio en blanco

1.7.1. Lneas en blanco
Se deben usar dos lneas en blanco entre2 : Diferentes secciones de un chero de cdigo fuente Entre clases y deniciones de interfaz Se debe usar una lnea en blanco: Mtodos Variables locales de un mtodo y la primera sentencia Antes de un bloque o un comentario de lnea (para que se sepa de un vistazo que es lo que comenta) Entre diferentes secciones lgicas dentro de un chero (ms legibilidad)

1.7.2. Caracteres de espacio

Se deben usar en las siguientes circunstancias: Entre un parntesis cerrado y una llave Despus de una coma en la lista de parmetros de un mtodo Entre operadores binarios: +, -, =, etc. Nunca entre un operador uno-ario y su operando La sentencia for y su parntesis. Ejemplo: for (expr1, expr2, expr3); Casts. Ejemplo: myMethod((int) (cp 5), ((int) (i + 3)) + 1);+

1.8. Asignacin de nombres

Esta es la seccin ms importante. Las normas genricas son: 1. Se usan descriptores en ingls que dejan claro el cometido de la variable, mtodo o clase. 2. Se usa terminologa aplicable al dominio. 3. Si se usan abreviaturas hay que mantener en algn sitio una lista de lo que signican.
2

Segn Sun. Esto no se est haciendo del todo as en este proyecto

4. Evitar en lo posible los nombres largos (menos de 15 letras sera lo ideal) 5. Evitar nombres que dieran en una letra o en el uso de maysculas. 6. Un nombre no debera constar de ms de dos palabras. 7. No usar siglas en los nombres a menos que queden muy largos o sean siglas conocidas por todos. Cada tipo de elemento debe nombrarse con una serie de reglas determinadas. Paquetes: Todo en minsculas. Cada palabra es ms especca que la anterior Clases e interfaces: Nombres. La inicial en mayscula Mtodos: Deben ser verbos. La primera letra de la primera palabra en minsculas, el resto de las palabras empiezan por maysculas Variables: Deben comenzar por minscula. No se utilizar en ningn caso el caracter "_" Constantes: Todo en mayscula. Si son varias palabras, unidas por el caracter "_"