Título: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: 3n31ch en 27 Enero 2015, 20:15 pm BUENAS PRÁCTICAS Y CONVENCIONES EN JAVA - PARTE UNO - CONVENCIONES Introducción El presente documento es la primera parte de lo que esperamos junto Gus Garsaky sea una guía para todos aquellos desarrolladores en java. Espero que les sea de utilidad y poder ayudar a todos los desarrolladores en java que aun no esten familiarizados con el concepto de buenas prácticas y convenciones. Es importante destacar que quizás exceptuando esta primera parte, el resto del documento puede ser de utilidad para desarrolladores sin importar el lenguaje de programación utilizado. Sin nada mas que agregar, empecemos con la parte uno, Convenciones. CONVENCIONES Es importante señalar que las convenciones presentadas acá están basadas en el documento Java Code Conventions publicado por Sun Mycrosystems el año 1997: http://www.oracle.com/technetwork/java/codeconventions-150003.pdf (http://www.oracle.com/technetwork/java/codeconventions-150003.pdf) Indice 1. Por qué convenciones de código. 2. Nombres de archivos. 3. Organización de archivos. 4. Indentación. 5. Comentarios. 6. Declaraciones. 7. Sentencias. 8. Espacios en blanco. A. Convenciones de capitalización. 9. Convenciones de nombres. 10. Hábitos de programación. 1. Por qué convenciones de código Las convenciones de código son importantes para los programadores por múltiples razones entre ellas, las mas destacadas:
2. Nombres de archivos 2.1 Extensiones de los archivos Los archivos en java utilizan las siguientes exenciones:
2.2 Nombres de archivos comunes Los nombres de archivos mas utilizados son:
3. Organización de archivos Un archivo consta de secciones que deben ser separadas por lineas en blanco y comentarios opcionales que identifiquen cada sección. Archivos con mas de 2000 lineas son engorrosos y deben ser evitados. 3.1 Archivos fuente de Java Cada archivo de fuente de Java contiene un sola clase o interfaces publica. cuando una clase o interfaces privada esta asociada con una clase publica, se puede poner el mismo archivo que la clase publica. La clase publica debe ser la primera clase o interfaces en el archivo. Código
Los archivos fuente de Java tienen el siguiente orden:
3.1.1 Comentarios de inicio Todo código fuente debe tener comentarios de inicio que señale el nombre de la clase, versión, una aviso de copyright , y también una breve descripción del propósito de la clase en el programa. Código
3.1.2 Sentencias de package e import La primera linea no-comentario de un archivo de fuente en java es la sentencia de package, posterior a esto, las sentencias de import. Código
3.1.3 Declaración de clases e interfaces La siguiente table describe las partes de la declaración de una clase o interface, en el orden que debe aparecer.
4. Indentación Se deben utilizar cuatro espacios por cada unidad de indentado. La construcción exacta del indentado (espacios vs. tabulaciones) no se especifica. Los tabuladores deben ser exactamente cada 8 espacios (no cuatro). 4.1 Longitud de línea Evitar mas de 80 caracteres por linea, ya que no son bien manejados por muchas terminales y herramientas. Nota: Ejemplos de uso en documentación deben ser mas breves - generalmente no mas de 70 caracteres. 4.2 Ajustes de líneas Cuando una expresión no quepa en una sola linea, debe ser cortada de acuerdo a los siguientes principios:
Ejemplos de cortes de llamadas métodos: Código
Ejemplos de cortes de operaciones aritméticas. Se prefiere el primero, ya que el salto de linea ocurre fuera de la expresión que encierra el paréntesis: Código
Ejemplos de indentación de declaraciones de métodos. El primer ejemplo es el caso convencional. El segundo se desplazaría la segunda y tercera linea muy a la derecha si se utiliza la sangría convencional, por lo que en vez de eso se utilizaron los 8 espacios de indentación: Código
El ajuste de linea para sentencias if por lo general usa la regla de 8 espacios, ya que el convencional (4 espacios) dificulta la lectura del cuerpo. Por ejemplo: Código
Aquí tres aceptables formas de expresiones ternarias: Código
5. Comentarios Los programas en java tienen dos tipos de comentarios: comentarios de implementacion y comentarios de documentación. los comentarios de implementacion son los que se encuentran en C++, los cuales son los delimitados por /*...*/, y //. Los comentarios de documentación (conocidos como "doc comments") están solo en java, y son delimitados por /**....*/. los comentarios de documentación pueden ser extraídos de archivos html utilizando las herramientas de javadoc. Los comentarios de implementación son para comentar código o para comentar una implementación en particular. los comentarios de documentado son para describir las especificaciones de el código, desde una perspectiva de implementación libre. Para ser leído por desarrolladores quienes no necesariamente tienen el código fuente en cuestión. Los comentarios podrían ser usados para obtener descripciones del código y proveer una información adicional que no es fácilmente deducible con el propio código. Los comentarios deben contener solo información que es relevante para el lector y el entendimiento del programa. Por ejemplo, la información sobre el paquete correspondiente en que se construye o el directorio en el que se encuentra el archivo no debe ser parte de un comentario. Decisiones no triviales o no obvias del diseño son apropiadas, pero se debe evitar la duplicación de la información que este presente y clara en el código. Nota: la frecuencia de los comentarios a veces refleja la mala calidad del código. Cuando usted se siente obligado a insertar un comentario, considere volver a escribir el código para hacerlo mas claro. Los comentarios no deben encerrarse en grandes cajas dibujadas con asteriscos u otros caracteres. Los comentarios nunca deben incluir caracteres espaciales. 5.1 Formato de comentarios de implementación: Los programas pueden tener cuatro estilos de implementación de comentarios: bloque, una linea, remolque y de fin de linea. 5.1.1 Comentarios de bloque: Los comentarios de bloque son usados para la descripción de archivos, métodos, estructuras de datos y algoritmos. Deben ser usados al principio de cada archivo y antes de cada método. También pueden ser usados en otros lugares como por ejemplo dentro de métodos. Los comentarios de bloques dentro de funciones o métodos deben tener una sangría al mismo nivel que el código a describir. Un código de bloque debe ser precedido por una linea en blanco para apartarlo del resto del código. Los comentarios de bloque tienen un asterisco "*" antes de cada linea. Código
Los comentarios de bloques pueden empezar con /*-, que es reconocido por el guion como un comentario de bloque que no debe ser reformado Código
Nota: Si no utilizas un indentado no debes utilizar /*- 5.1.2. Comentarios de una sola linea Comentarios cortos pueden ser incluidos en una sola linea indentados de tal manera que se encuentre al mismo nivel del código que describen. Si un comentario no puede ser escrito en una sola linea, se debe utilizar un comentario de bloque. Un comentario de una sola linea debe ser precedido por una linea en blanco. Código
5.1.3. Comentarios de remolque Comentarios muy cortos pueden aparecer en la misma linea del código que describen, pero debe ser indentado de tal manera de que este se encuentre lejos del código. Si existe mas de un comentario con estas características, todos deben ser indentados al mismo nivel. Código
5.1.4. Comentarios de fin de linea El delimitador de comentarios // puede convertir en comentario una linea. Puede comentar una linea completa o solo parte de ella. No debe ser usado consecutivamente en múltiples lineas para textos extensos; sin embargo, se puede usar consecutivamente para comentar secciones de código. Código
5.2 Comentarios de documentado Los comentarios de documentado describen clases, interfaces, constructores, métodos y archivos. Cada comentario de documentado es creado dentro de los delimitadores /**...*/. Código
Java asocia los comentarios de documentado a la siguiente declaración posicionada posterior el comentario de documentado, por esta razón estos comentarios no deben ser ingresados dentro de los métodos o secciones que se intentan describir. Nota: Los comentarios de documentado serán vistos mas afondo en otra parte independiente de este documento, por el momento para mas información: http://www.oracle.com/technetwork/articles/java/index-137868.html (http://www.oracle.com/technetwork/articles/java/index-137868.html) 6. Declaraciones 6.1. Numero de declaraciones por línea Se recomienda una declaración por línea, ya que facilita la adición de comentarios. Por esta razón se prefiere: Código
Antes que: Código
No poner diferentes tipos en la misma linea. Ejemplo: Código
Nota: Los ejemplos anteriores usaban un espacio entre el tipo y el nombre identificador. Otra alternativa aceptable es usar tabulaciones: Código
6.2. Ubicación Localizar las declaraciones solo al inicio de los bloques (Los bloques son aquellos delimitados por {}). No esperar a declarar variables antes de su primer uso; esto puede llegar a ser confuso para el programador, y probablemente pueda omitir una declaración. Código
La única excepción a esta regla es en caso de los ciclos for, ya que en Java se pueden declarar dentro del ciclo for Código
Evitar declarar variables que tengan el mismo nombre que algún atributo de la clase que la contiene. Código
6.3. Inicialización Intentar inicializar las variables locales en el mismo momento en que son declaradas. A menos que no pueda ser inicializada porque su valor depende de cálculos realizados por el programa posterior a su declaración. 6.4. Declaración de clases e interfaces Cuando programa en java clases e interfaces, debe seguir el siguiente formato de reglas:
Código
7. Sentencias 7.1. Sentencias simples Cada linea debe tener solo una sentencia. El siguiente ejemplo es incorrecto. Código
7.2 Composición de sentencias Las sentencias compuestas son sentencias que contienen listas de sentencias encerradas entre llaves. Las sentencias encerradas deben tener una indentación mas que su nivel superior Las llaves de inicio deben estar al final de la linea que comienza la sentencia compuesta; la llave de cierre debe empezar en una nueva linea y ser indentada al mismo nivel que el principio de la sentencia compuesta. Las llaves se usan en todas las sentencias, sin importar su simplicidad. Esto hace mas fácil añadir nuevas sentencias. 7.3. Sentencias return Una sentencia que retorna un valor no debe usar paréntesis, amenos que hagan que el valor de retorno sea mas evidente de alguna manera. 7.4. Sentencias if, if-else, if-else-if-ese Las sentencias if-else deben seguir el siguiente formato: Código
Nota: La sentencia if siempre debe usar llaves. con el fin de evitar errores. 7.5. Sentencias for Una sentencia for debe seguir el siguiente formato: Código
Una sentencia for bacía debe seguir el siguiente formato: Código
Si se utiliza una coma en la inicialización, condición, o actualización se debe evitar usar mas de tres variables. Si aun así, es necesario, es recomendado separar la sentencia, declarando las variables antes del bucle o actualizando en el bucle 7.6. Sentencias while Una sentencia while debe seguir el siguiente formato: Código
Una sentencia while bacía debe seguir el siguiente formato Código
7.7. Sentencia do-while Una sentencia do-while debe seguir el siguiente formato: Código
7.8. Sentencia switch Una sentencia switch debe seguir el siguiente formato: Código
Siempre que un caso se propague (no incluya sentencia break), añadir un comentario donde la sentencia break se encontraría normalmente. Cada sentencia switch debe incluir un caso por defecto. El break del caso por defecto es redundante, pero evita que se propague por error si se añade otro caso. 7.9. Sentencia try-catch Una sentencia try-catch debe seguir el siguiente formato: Código
8. Espacios en blanco 8.1. Líneas en blanco Las lineas en blanco nos permite separar secciones de código que están lógicamente relacionadas. Se debe usar siempre dos lineas en blanco para las siguientes circunstancias:
Se debe usar siempre un linea en blanco en las siguientes circunstancias:
8.2. Espacios en blanco Los espacios en blanco son usados en las siguientes circunstancias:
A. Convenciones de capitalización Nota: Esta sección ha sido a agregada con el propósito de facilitar la comprensión de la sección 9. Convenciones de nombres Muchas de las convenciones de nombre tienen como objetivo la correcta "Capitalización" a la hora de declarar los nombres de paquetes, clases, métodos, variables, constantes... Al utilizar la palabra "Capitalización" se intenta referir a la utilización de mayúsculas y minúsculas a la hora de crear un nombre identificador para los elementos anteriormente mencionados. Existen distintos tipos de Capitalización y en este caso 4(3+1): A.1. Pascal case: Se refiere a utilizar mayúsculas en la inicial de cada palabra y el resto de las letras tendrán que ser minúsculas sin excepción alguna. Código
A.2. Camel case: Se refiere a utilizar mayúsculas en la inicial de cada palabra con excepción de la primera letra de la primera palabra y el resto de las letras tendrán que se minúsculas. Código
A.3. Upper case: Se refiere a utilizar mayúsculas en todo el conjunto. Código
A.4. Lower case: Se refiere a utilizar minúsculas en todo el conjunto. Código
Nota: Este ultimo fue agregado para efectos de este documento en especifico. 9. Convenciones de nombres Las convenciones de nombres hacen a los programas mas fáciles de leer. También dan información acerca de un elemento solo con leer su nombre lo que resulta muy útil a la hora de entender el código.
10. Hábitos de programación 10.1. Acceso a variables de instancia y de clase: Por principios de encapsulación ninguna variable de instancia o clase a de ser publica sin una buena razón. Para acceder a variables de instancia o clase se utilizan los denominados métodos set o get. 10.2. Acceder a variables y métodos de clase Evitar usar un objeto para acceder a una variable o método de clase. Usar el nombre de la clase en su lugar. Código
10.3. Constantes Las constantes numéricas no se deben codificar directamente, excepto se trata de un bucle for. 10.4. Asignacion de variables Evitar asignar el mismo valor a variables en la misma sentencia. Código
10.5. Hábitos varios 10.5.1. Paréntesis Es muy recomendado usar paréntesis en expresiones que implican distintos operadores aun cuando no sea necesario. Esto facilita la comprensión del código. 10.5.2. Valores de retorno Es apropiado hacer que la estructura del programa se ajuste a su intención. Por Ejemplo: Código
En lugar de hacer: Código
10.5.3. Expresión ternaria Si una expresión incluye un operador binario antes del signo ? en el operador ternario , se debe colocar entre paréntesis. Ejemplo: Código
10.5.4 Comentarios especiales Usar XXX en un comentario para indicar que algo tiene algún error pero funciona. Usar FIXME para indicar que algo tiene algún error y no funciona. Muchas gracias por leer, y espero que les sea de ayuda. Título: Re: Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: 3n31ch en 27 Enero 2015, 20:19 pm Disculpen la demora, pero entre traducir y transcribir para que se vea bonito en el foro me demore un año :xD
Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: vangodp en 28 Enero 2015, 00:58 am ...y ahora la parte numero 2 que esta esta muy mona. XD ;-)
Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: 3n31ch en 28 Enero 2015, 05:16 am Creo que esa la hará Gus Garsaky, Patrones de diseño ^^
Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: MNicolas en 28 Enero 2015, 17:05 pm De verdad admiro a la gente que se dedica a ayudar desinteresadamente a los demás!
;-) Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: Usuario Invitado en 28 Enero 2015, 17:25 pm En éstos días publicaré los patrones de diseño más usados y sus ventajas y desventajas.
Salu2. Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: 3n31ch en 31 Enero 2015, 07:41 am La siguiente parte realizada por Gus Garsaky ya se encuentra disponible:
[Guía] Patrones de diseño - Parte 1 (http://"http://foro.elhacker.net/java/guia_patrones_de_diseno_parte_1-t429045.0.html") Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: hossman92 en 5 Febrero 2015, 15:29 pm muy buen aporte gracias me esta sirviendo mucho par dejar bonito mi codigo :D :D
Título: Re: [APORTE] Buenas prácticas y convenciones en Java - Parte uno - Convenciones Publicado por: BlackZeroX en 22 Agosto 2015, 21:56 pm falta mucho por ejemplo de losDTO, VO, declaración de las interfaces y manejo de capas, servicios, pools, contenedores de persistencia (como meta-container), uff pero esta genial aun asi :)
Dulces Lunas!¡. |