Guía de estilo de programación en Java Pequeños consejos sobre sobre cómo escribir programas programas más legibles.
Índice Guía de estilo de programación en Java....................................................................................... Java...............................................................................................1 ........1 1Introducción................................. 1Introducción............................................................... ............................................................... ............................................................... ...................................3 .....3 2Indicaciones generales........................................... generales................................................................................. ........................................................................3 ..................................3 3Identificadores................................................ 3Identificadores................................................................................................. ...............................................................................5 ..............................5 3.1Identificadores 3.1Identificadores de clases.......................................................................................... clases........................................................................................................5 ..............5 3.2Identificadores 3.2Identificadores de atributos y variables locales.....................................................................6 3.3Identificadores 3.3Identificadores de constantes...................................................................... constantes.................................................................................................6 ...........................6 3.Identificadores 3.Identificadores de ob!etos..................................... ob!etos................................................................................................. ................................................................." ....." 3.5Identificadores 3.5Identificadores de m#todos................................. m#todos............................................................................................... ..................................................................." ....." 3.5.1Identificadores 3.5.1Identificadores de variables locales en m#todos............................................................" 3.6$efinición de variables locales..............................................................................................% locales..............................................................................................% &omentarios................................. &omentarios............................................................... ............................................................... ............................................................... ...................................' .....' .1&omentarios de inicio de blo(ue.......................................... blo(ue...................................................................... ..................................................' ......................' .2&omentarios aclaratorios..................................... aclaratorios............................................................ ................................................ ..........................................1) .................1) .3&omentarios sobre m#todos..................................................... m#todos.............................................................................................. ............................................1) ...1) 5$isposición de elementos............................................................................................ elementos............................................................................................................11 ................11 5.1&lases.................................................... 5.1&lases................................................................................................... ...............................................................................11 ................................11 5.2$isposición de elementos en cada fic*ero...........................................................................12 fic*ero...........................................................................12 5.3+#todos........................... 5.3+#todos..................................................... ................................................... ................................................... ..................................................13 ........................13 5.3.1,structuras de decisión y repetición..................................................... repetición.............................................................................1 ........................1 6-ibliografía............................................. 6-ibliografía................................................................................. .................................................................... .................................................15 .................15
Guía de estilo de programación en Java
2
Guía de estilo de programación en Java 1 Introducción ,n este documento se eplica brevemente/ y con e!emplos/ cómo escribir programas m0s sencillos de entender. lo largo de su vida profesional/ cual(uier programador se plantea la pregunta de cómo escribir sus programas de manera (ue sean m0s legibles/ y por tanto (ue puedan ser mantenidos corrección de errores/ ampliación de funcionalidad con facilidad/ tanto por #l mismo como por otros programadores una situación típica en cual(uier empresa. $ado (ue la misma situación en cuanto a legibilidad de código suele ser resuelta por distintos programadores de la misma forma/ pero con distintos matices de diferenciación/ es interesante seguir una guía de estilo (ue nos epli(ue como otros resolvieron ese mismo problema/ *asta (ue dic*a solución se convirtió en un est0ndar. 2 Indi Indica caci cion ones es gene genera rale les s ,l propósito de seguir una norma de estilo es *acer (ue el código fuente de un programa sea tan legible como sea posible. sí/ *ay tres puntos b0sicos (ue se deben cuidar4 el espaciado *oriontal/ el espaciado vertical y la indentación. ,l espaciado *oriontal consiste en (ue las líneas en las (ue est# dividido el código fuente deben ser de una longitud m0ima lo m0s próima posible a ") caracteres/ ya (ue al imprimir el código en papel cual(uier línea superior a %) columnas se corta autom0ticamente. no de los problemas (ue se puede encontrar al codificar es la manera m0s correcta para dividir una línea muy larga. 7espuestas comunes a esta pregunta son4 despu#s de una coma en una llamada a un m#todo/ por e!emplo. antes de una subepresión/ antes de un operador/ o antes de un par#ntesis. 8or 8or e!emplo4 int x = ( (a * b + c ) / ( c * d * d ) )
+ ( a / ( b * c ) ) + ( ( 3.1451927 * b ) + d );
9e recomienda separar las palabras reservadas if / while.../ los operadores/ así como los par#ntesis/ mediante espacios para mayor claridad/ a ecepción *ec*a de operadores unarios como el incremento o decremento/ tanto postfi!o como prefi!o/ (ue suelen colocarse pegados al operando al (ue modifican. ,l uso típico incluye adem0s el separar con un espacio los argumentos en las listas de par0metros formales y de argumentos/ los corc*etes del operador de subíndice/ y los operadores como :/ ;. . int x = a + b; int z = Math.pow( x, y );
n!"#$%&t'o& = .&%z#() + '#$%&t'o&ab#c#'a % ; if ( x - )
// !& co&a&... 0
,l espaciado vertical consiste en cu0ntas líneas ocupa un m#todo/ o una clase/ en el código fuente. ,n general/ es ?til autoimponerse un límite de una *o!a por cada m#todo. ,s etra@o/ siempre (ue la función miembro no consista en multitud de acciones repetitivas como escribir en 3
Guía de estilo de programación en Java un arc*ivo/ o realiar una serie de incialiaciones/ (ue una función miembro bien dise@ada ocupe m0s all0 de un folio. ,n caso contrario/ ser0 conveniente considerar (ue posiblemente sea interesante subdividirlo en varios m#todos privados. dem0s/ en el espaciado vertical intervienen las llaves (ue se emplean para marcar el comieno y fin del cuerpo de una función/ de un bucle/... cada una de esas llaves puede llegar a consumir una línea por sí sola/ incluso dos. sí/ para salvar algo de espacio vertical/ se suelen mantener las llaves de apertura y cierre/ cada una en una línea/ para el cuerpo de las funciones miembro y funciones/ y en cambio colocar la llave de apertura en la misma línea para bucles y estructuras de decisión a esto se le conoce como estilo Kernighan&Ritchie. 8or e!emplo4 public class class Mat#& public static static int d%%d#(int a, int b)
if ( b = - ) return a / b;
0 return -; 0 // !& co&a&...
0
...si bien en un programa real ser0 muc*o m0s adecuado responder a la contingencia (ue supone dividir un n?mero entre cero/ (ue responder con cero AsilenciosamenteB/ lo cual supone un error no detectado. sí/ por regla general la llave de apertura se coloca en la misma línea/ siempre y cuando no se trate de la llave de apertura de un m#todo/ o (ue en una sentencia if se encuentren varias subcondiciones. Ca indentación es vital para poder comprender r0pidamente los elementos funcionales de un programa. sí/ el cuerpo las instrucciones de una función o función miembro debe estar alineado en su margen i(uierdo m0s a la derec*a (ue la cabecera de una función/ de la misma forma (ue un bucle dentro de esa función y así así sucesivamente. sucesivamente. 8or e!emplo4 public class class Mat#& public static static int ##a(int x, int y)
int to'#t = x; for(; y 1; y)
to'#t *= x; 0 return to'#t;
0 0
Guía de estilo de programación en Java 3 Iden Identi tifi fica cado dore res s Cos identificadores se utilian en varias innumerables ocasiones en programación4 clases/ atributos/ m#todos/ constantes/ variables locales .../ y son claves para entender (u# valores puede contener una variable/ (u# *ace una función miembro o a (u# ob!etos representa una clase. 8or eso/ *ay (ue poner especial cuidado en su elección. Dambi#n ser0 interesante seguir unas pe(ue@as reglas a la *ora de escribir un identificador (ue *agan (ue a su ve podamos obtener el m0imo significado del mismo si se est0 leyendo en un listado. ,n general/ los identificadores deben ser tan cortos como sea posible/ pero a la ve tan informativos como sea posible. ,n general/ las clases/ atributos y variables locales se nombrar0n con sustantivos Coche/ Casa/ mientras para los m#todos se utiliar0n verbos en su forma imperativa divide/ compara. +uc*as veces/ adem0s/ es imposible utiliar un solo sustantivo para nombrar una clase/ atributo/ o variable localE en ese caso/ se concatenar0n todos para formar el identificador final/ poniendo cada inicial en may?scula. 9i bien algunos lengua!es modernos lo permiten como Java/ a trav#s del soporte unicode/ evítense los acentos/ las di#resis... en los identificadores.
3. 3.11 Iden Identi tifi fica cado dore ress de de cla clase sess Cos identificadores de clases deberían corresponderse con sustantivos de la vida real o del concepto (ue se est0 modelando con el programa. sí/ identificadores de clases pueden ser4 Casa/ Coche/ Barco/ Cuenta... ,l identificador de la clase/ en caso de estar compuesto por m0s de una palabra/ se construye concatenando concatenando todas las palabras/ y poniendo la inicial de cada una de estas palabras en may?sculas. 8or e!emplo4 CuentaCorriente/ VehiculoConMotor/ VehiculoSinMotor. public class class "#ctan$o
// !& co&a& ... 0 public class class %'co
// !& co&a& ... 0 public class class och#
// !& co&a& ... 0 public class class #ntao''%#nt#
// !& co&a& ... 0
5
Guía de estilo de programación en Java
3.2 Ident Identifi ificad cadore ores s de atribut atributos os y variabl variables es locale localess Cos identificadores de datos miembro siguen las mismas normas (ue los de las clases/ pero con la primera inicial en min?scula. sí/ por e!emplo/ identificadores v0lidos son identificadorompleto/ precio!uros precio!uros/ ... public class class #ntao''%#nt# private double double &ado'o&; public #ntao''%#nt#(double &ado)
&ado'o& = &ado; 0 public double double $#tado()
return &ado'o&;
0 // !& co&a& ... 0
3. 3.33 Iden Identi tifi fica cado dore res s de const constan ante tess Cos identificadores de constantes siguen un formato muy especial4 siempre en may?sculas/ y en caso de contener varios nombres/ estos se concatenan utiliando el car0cter subrayado FF. ,sto incluye las constantes de los enumerados. public class class #ntao''%#nt# public static static final double double 6"88: = 1<<.3<; public enum %po#nta %po#nta >"", >""8?@A"?@8BC >""8?@A"?@8BC 0; private double double &ado'o&; %po#nta t%po#nta; private public #ntao''%#nt#(double &ado, %po#nta t%po)
&ado'o& = &ado; t%po#nta = t%po; 0 public %po#nta $#t%po#nta() return t%po#nta;
0 public double double $#tado() return &ado'o&;
0
public double double cacaadon:#&#ta&() return $#tado() * 6"88:; 6"88:;
0 // !& co&a& ... 0
6
Guía de estilo de programación en Java
3. 3.44 Iden Identi tifi fica cado dore res s de ob obet etos os Cos identificadores de ob!etos siguen las mismas reglas (ue los identificadores de atributos y variables locales. public class class :pa !a%n( !a%n(string a'$&) public static static void
#ntao''%#nt# c#nta = new #ntao''%#nt#( 5--, #ntao''%#nt#.%po#nta.>"" ); y&t#!.ot.p'%ntn( DadoE D + c#nta.$#tado() ); 0 0
3. 3.!! Iden Identi tifi fica cado dore res s de m"t m"tod odos os Cos identificadores de funciones miembro siguen las mismas reglas de may?sculas y min?sculas (ue para atributos/ variables locales y ob!etos. 9in embargo/ deben escogerse verbos de manera (ue sugieran de manera intuitiva (u# *acen. sí/ el identificador debe ser un verbo en imperativo o al menos contener uno. Cos m#todos (ue sirven para obtener el valor de un atributo deben llevar el prefi!o get . int $#tdad(); boolean #&:a%nd'o!o(t'%n$ &);
,vítensen identificadores como los siguientes4 int p' p'oc#&a'(F%# G); t'%n$ t'%n$ pa&o pa&ox% x%%a' %a'(t (t'%n '%n$ $ ax); ax); void p' p'oc#&aI#nta();
// MaE %d#nt%G%cado' no %nt%t%o // MaE MaE %d#nt% %d#nt%G%c G%cado ado' ' #''Hn# #''Hn#o o // MaE J%%d%' #n do& Gnc%on#&
&uando un identificador contiene una con!unción como "/ es signo ine(uívoco de (ue la función (ue nombra realia m0s de una tarea y debe ser por tanto separada en dos funciones separadas. Cos me!ores identificadores son a(uellos (ue describen con un identificador m0s corto/ y a la ve de manera m0s específica lo (ue *ace el m#todo. dem0s/ es interesante seguir ciertas pautas4 en el caso de funciones miembro (ue devuelven un booleano un valor verdadero o falso/ es interesante nombrarlos con un prefi!o formado por los verbos ser o estar/ como4 boolean #&:a%nd'o!o(t'%n$ &); boolean #&:a'(int x); boolean G#Mod%G%cada(:#'&ona p);
3.5.1 3.5.1 Identif Identificad icadores ores de de variabl variables es local locales es en métod métodos os
,n el caso de variables locales de funciones miembro/ eisten varias particularidades. 8or e!emplo/ a las variables locales empleadas en bucles se les suele asignar identificadores de una letra tipo FiF y F!F/ tambi#n en el caso de algunos argumentos simples de m#todos como FsF o FF/ si bien este caso es me!or/ sin embargo/ evitarlo/ cuando sea posible/ y asignar identificadores descriptivos. public class class ad#na& public static t'%n$ cap%ta%za?n%c%a(t'%n$ &)
"
Guía de estilo de programación en Java &.to6pp#'a&#().cha't( t( - ) return &.to6pp#'a&#().cha' + &.toCow#'a&#().&b&t'%n$( 1 ); 0 0
Cos identificadores de variables tambi#n pueden informar sobre para (u# se utilia esa variable/ y no restringirse a tan solo información sobre (u# valores alberga. 8or e!emplo/ en el código siguiente toret a a retornar es una variable (ue se utilia en todas las funciones para devolver un valor. public class class ad#na& public static static t'%n$ #xt'a#on&onant#&(t'%n$ &)
final t'%n$ oca#& = Da#%oK; t'%n$B%d#' t'%n$B%d#' to'#t = new t'%n$B%d#'(); for (int % = -; % L &.#n$th(); ++%) final char ch = &.cha't( % ); if ( oca#&.%nd#xG( ch ) L - )
// @o #ncont'ado #n oca#&, %n&#'ta' to'#t.app#nd( to'#t.app#nd( ch ); 0 0 to'#t.tot'%n$(); return to'#t.tot'%n$(); 0 0
3.# $efini $efinició ción n de variab variables les locale localess 9e debe colocar cada variable en una línea/ incluso siendo del mismo tipo/ para maimiar la legibilidad. Cas variables locales siempre se colocan al comieno de cada blo(ue/ (ue siempre va delimitiado por llaves FHF y FF. Dambi#n Dambi#n debe tratarse de inicialiar las variables lo antes posible. public class class :pa x, y; private int x,
// MC
!a%n(t'%n$ a'$&) !a%n(t'%n$ public static static void int x = -; int y = 1; c, c2; char c,
// MC
t'%n$ to'#t = DK; // !& co&a& ... 0 0
%
Guía de estilo de programación en Java 4 Comentarios n comentario debe ser siempre clarificador/ ?til/ y/ en cambio/ cuanto m0s corto me!or. ,n particular/ particular/ debe cuidarse en no insultar la inteligencia del lector en determinadas ocasiones/ comentando secuencias de código obvias y desesperarlo al encontrarse con construcciones comple!as (ue no tienen ning?n comentario. a'#a"#ctan$o = ado1 * ado2; int a'#a"#ctan$o
// caca '#a // caca '#a d# c'co // :? #& 3.1415927
a'#a%'co = :? * ' * ';
,n el conteto del e!emplo anterior/ el tercer comentario es absolutamente innecesario/ mientras (ue los dos primeros son cuestionables/ siempre (ue los identificadores *ayan sido escogidos cuidadosamente/ cuidadosamente/ como es el caso. &uando los identificadores son tan significativos (ue el propósito es obvio/ el código se conoce como autocomentado. ,sto no (uiere decir (ue los comentarios sean siempre opcionales. a'#a"#ctan$o = ado1 * ado2; int a'#a"#ctan$o
// caca # '#a #n c!&N2
4.1 %oment %omentari arios os de inici inicio o de de blo& blo&ue ue ,isten dos tipos b0sicos de comentarios/ los (ue podríamos denominar comentarios encima/ y los (ue podríamos denominar comentarios a la derecha. Cos m0s recomendables son los primeros/ pues suelen eplicar un blo(ue de código/ a modo de p0rrafo/ aclarando muc*o la lectura. public class class :#'&ona public :#'&ona(t'%n$ n, int #)
no!b'# = n; #dad = #; 0 public t'%n$ $#t@o!b'#()
return no!b'#;
0 public int $#tdad()
#dad; return #d
// n aOo&
0 public t'%n$ tot'%n$()
// Fo'!at#a' no!b'# t'%n$ no!b'# = ad#na&.cap%ta%za?n%c%a( $#t@o!b'#() ); // on&t'%' %nGo d# p#'&ona t'%n$ to'#t = $#t@o!b'#() + DE D + $#tdad(); '#t'n to'#t; 0 0
'
Guía de estilo de programación en Java
4. 4.22 %ome %oment ntar ario ioss acl aclar arat ator orio ioss Cos comentarios a la derecha deben emplearse como mensa!es aclaratorios/ intentando mantener especialmente en ellos la concisión/ pues es f0cil (ue se alcancen r0pidamente m0s de oc*enta caracteres en esa línea. gravando a?n m0s este ?ltimo problema/ deben colocarse ale!ados del código (ue aclaran para (ue sean visibles. // co& p'#%o& a '#nd#'%n$ a'#a"#ctan$o a'#a"#ctan$o = ado1 * ado2;
// #n c!&
4. 4.33 %ome %oment ntar ario ioss sob sobre re m"to m"todo doss $esde la llegada del lengua!e Java/ y su *erramienta de documentación/ #avadoc/ se *an generaliado los comentarios formateados con un determinado estilo/ y aceptando unos determinados par0metros de documentación embebidos en ellos. sí/ cuando un comentario/ en lugar de empear por <;/ comiena por <;;/ o un comentario de línea/ en lugar de empear por <
1)
Guía de estilo de programación en Java public double double $#tt'a()
return at'a;
0 /** * aca a &p#'G%c%# d# a G%$'a * P'#t'n Ca &p#'G%c%# d# a G%$'a, co!o dob# */ caca'#a() public double double caca'#a() return $#tBa&#() * $#tt'a(); 0 0
$e los par0metros (ue se pueden utiliar en este tipo de comentarios/ destacan $param y $return . ,l primero sirve para documentar un par0metro de una función miembro. tal y como se ve en el constructor de la clase Rectangulo de e!emplo/ m0s arriba. ,l segundo sirve para documentar el valor de retorno de una función miembro/ tal y como se aprecia en la función miembro calculaArea() de la clase del mismo e!emplo. 5 Disp Dispos osic ició ión n de ele eleme ment ntos os
!.1 %lases $ebe escogerse una forma de disponer los miembros en la clase/ y tratar de mantenerla. 8or e!emplo/ la m0s etendida consiste en colocar la parte p?blica de la clase lo m0s cercana a la parte superior. superior. Ksto tiene sentido por(ue cuando trate de leer el código/ al programador le interesa la parte p?blica de la clase/ (ue es la (ue tendr0 (ue mane!ar/ y no la l a parte privada o protegida/ de la (ue sólo tendr0 (ue preocuparse si es el (ue la l a mantiene. 8or tanto/ un buen es(uema es colocar primero los atributos y despu#s los m#todos. $entro de cada grupo irían primero los miembros p?blicos/ despu#s los protegidos/ y finalmente los privados. /// "#p'#&#nta a o& pnto& d# do& d%!#n&%on#& class :nto private int x; private int y;
/** * on&t'cto' d# obQ#to& pnto * Ppa'a! Ppa'a! a Ca Ca coo'd#nada coo'd#nada ho'%zonta * Ppa'a! Ppa'a! b Ca Ca coo'd#nada coo'd#nada #'t%ca */ public :nto( int a, int b) x = a; y = b; 0 /// P'#t'n a coo'd#nada ho'%zonta public int $#tR() return x; 0
11
Guía de estilo de programación en Java /// P'#t'n a coo'd#nada #'t%ca public int $#tI() return y; 0 0
!.2 $is $ispos posici ición ón de de eleme elemento ntoss en cada cada fic'e fic'ero ro &ada fic*ero ;.!ava en Java debe contener eactamente una clase/ y el nombre del arc*ivo debe coincidir con esa clase. Co primero (ue debe aparecer en el arc*ivo es un comentario describiendo la información de versión de la clase. continuación/ la sentencia pac%age/ si es necesaria. $espu#s los import (ue (ue se utilicen/ y a continuación la clase en sí. /* * :nto * * 1.* * F#chaE 2-14/12 * * C%c#nc%a M? */ /// "#p'#&#nta a o& pnto& d# do& d%!#n&%on#& public class class :nto public static static final :nto "?S@ = new :nto( -, - ); private int x; private int y;
/** * on&t'cto' d# obQ#to& pnto * Ppa'a! Ppa'a! a Ca Ca coo'd#nada coo'd#nada ho'%zonta * Ppa'a! Ppa'a! b Ca Ca coo'd#nada coo'd#nada #'t%ca */ public :nto( int a, int b) x = a; y = b; 0 /// P'#t'n a coo'd#nada ho'%zonta public int $#tR()
return x;
0 /// P'#t'n a coo'd#nada #'t%ca public int $#tI() return y; 0
12
Guía de estilo de programación en Java /// P'#t'n a %nGo d# pnto, co!o t'%n$ public t'%n$ tot'%n$() return ( $#tR() + T, T + $#tI() ); 0 0
$entro de la clase/ los elementos se disponen de la forma siguiente4 primero las constantes atributos marcados como final/ los miembros static/ a continuación los atributos/ y despu#s el constructor y los m#todos. ,l orden dentro de cada AsecciónB siempre es el mismo/ de public a private. &ada sección se separa de la anterior por una línea en blanco. &ada m#todo se separa del anterior por una línea en blanco.
!.3 ("todos ,n las funciones/ se debe adoptar como es(uema b0sico la típica estructura inicialiación> desarrollo>limpiea/ es decir el comieno de la tarea/ inicialiando y creando/ cuando sea oportuno las variables necesarias/ el desarrollo del problema/ como el bucle del e!emplo situado m0s aba!o/y finalmente/ cuando es necesario/ la limpiea de los recursos utiliados. public class class ''ay6t%
/** * oncat#na do& #cto'#& d# #nt#'o& * Ppa'a! 1 p'%!#' #cto' d# #nt#'o& * Ppa'a! Ppa'a! 2 &#$ndo &#$ndo #cto' d# #nt#'o& #nt#'o& * P'#t'n& P'#t'n& n n#o #cto' #cto' d# #nt#'o&E 1 + 2 */ public static int concat#naA#cto'#&(int 1, int 2) int to'#t = n#w %nt 1.#n$th + 2.#n$th ; int po& = -; // op%a # p'%!#' #cto' #n # '#&tado for(int xE 1) to'#t po& = 1 po& ; ++po&; 0 // op%a # &#$ndo #cto' #n # '#&tado for(int xE 2) to'#t po& = 2 po& 1.#n$th ; ++po&; 0 return to'#t;
0 0
13
Guía de estilo de programación en Java 5.3.1 5.3.1 Estruc Estructur turas as de decisi decisión ón repet repetici ición ón
,s típico encontrarse con la necesidad de tener (ue crear estructuras condicionales if o de repetición while/ (ue se refieren a condiciones comple!as. $ebe tratarse/ en estos casos/ de disponer una una subcondición subcondición por línea/ línea/ comenando comenando por el el !untor and LL/ or MM/ MM/ y not N. N. 9i es necesario/ una subcondición puede llevar un comentario Oa la derec*aO. 9i eisten varias subepresiones subepresiones condicionales/ se deben indentar respecto a la epresión principal. if ( 1.#n$th -
UU 2.#n$th - ) int po& = -; while( po& L 1.#n$th )
// !& co&a& ... 0 if ( po& = 1.#n$th
UU po& = 2.#n$th ) 2 po& = 1 po& V 2.#n$th ; 0 0
Punca deben deben crearse blo(ues blo(ues (ue no consten consten de una llave llave de comieno y otra de final. if ( 1.#n$th -
UU 2.#n$th - ) 2 - = 1 - ;
// MC
1
Guía de estilo de programación en Java ! "ibliograf#a Programación . 8rentice>all. 1. Kernighan, Ritchie (1991). !l lenguaje de Programación
2. Guía de estilo estilo de progra programació maciónn en Java de Qracle Qracle *ttp4<136)5" convtoc>136)5".*tml .*tml 3. Guía de estilo estilo de progra programació maciónn en Java de Google Google *ttps4<styleguide.googlecode. *ttps4<styleguid e.googlecode.com
15
