Advertisement
  1. Code
  2. HTML & CSS

Las 15+ Mejores Prácticas para Escribir Código Super Legible

by
Read Time:12 minsLanguages:

Spanish (Español) translation by Jorge Montoya (you can also view the original English article)

Dos veces al mes, revisamos algunas de las publicaciones favoritas de nuestros lectores durante la historia de Nettuts+.

La legibilidad del código es un tema universal en el mundo de la programación de computadoras. Es una de las primeras cosas que aprendemos como desarrolladores. Este artículo detallará las quince prácticas más importantes para escribir código legible.


1 - Comentar y Documentar

Los IDE (Entornos de Desarrollo Integrado) han recorrido un largo camino en los últimos años. Esto ha hecho que comentar su código sea más útil que nunca. Seguir ciertos estándares en sus comentarios permite que los IDE y otras herramientas los utilicen de diferentes maneras.

Considere este ejemplo:

Los comentarios que agregué en la definición de función se pueden observar en una vista previa siempre que use esa función, incluso desde otros archivos.

Aquí hay otro ejemplo donde hago un llamado una función desde una biblioteca de terceros:

En estos ejemplos particulares, el tipo de comentario (o documentación) utilizado se basa en PHPDoc, y el IDE es Aptana.


2 - Sangrado consistente

Supongo que usted ya sabe que debe sangrar su código. Sin embargo, también vale la pena señalar que es una buena idea mantener su estilo de sangrado de una manera coherente.

Hay más de una forma de sangrar el código.

Estilo 1:
Estilo 2:
Estilo 3:

Solía ​​codificar en estilo #2, pero recientemente cambié a # 1. Pero eso es sólo una cuestión de preferencia. No existe el "mejor" estilo que todo el mundo debería seguir. De hecho, el mejor estilo es un estilo consistente. Si usted forma parte de un equipo o si está contribuyendo con código a un proyecto, debe seguir el estilo existente que se está utilizando en ese proyecto.

Los estilos de sangrado no siempre son completamente distintos entre sí. A veces mezclan diferentes reglas. Por ejemplo, en los Estándares de Codificación de PEAR, la llave "{" va en la misma línea que las estructuras de control, pero van en la siguiente línea después de las definiciones de función.

Estilo PEAR:

También tenga en cuenta que se están utilizando cuatro espacios en lugar de tabuladores para las sangrías.

Aquí hay un artículo de Wikipedia con muestras de diferentes estilos de sangría.


3 - Evite Comentarios Obvios

Comentar su código es fantástico, sin embargo puede estar sobrecomentado o simplemente redundante. Tome este ejemplo:

Cuando el texto es así de obvio, realmente no es productivo repetirlo dentro de los comentarios.

Si tiene que comentar ese código, en vez de eso usted simplemente puede combinarlo en una sola línea:


4 - Agrupación de Código

Casi siempre ciertas tareas requieren unas pocas líneas de código. Es una buena idea mantener estas tareas dentro de bloques separados de código, con algunos espacios entre ellos.

Aquí hay un ejemplo simplificado:

La adición de un comentario al principio de cada bloque de código también enfatiza la separación visual.


5 - Esquema de Nomenclatura Consistente

El mismo PHP es a veces culpable de no seguir esquemas de nomenclatura consistentes:

  • strpos() vs. str_split()
  • imagetypes() vs. image_type_to_extension()

En primer lugar, los nombres deberían tener límites en sus palabras. Hay dos opciones populares:

  • camelCase: La primera letra de cada palabra está en mayúscula, excepto la primera palabra.
  • Guiones bajos: Guiones bajos entre palabras, tales como: mysql_real_escape_string ().

Tener diferentes opciones crea una situación similar a los estilos de sangrado, como mencioné anteriormente. Si un proyecto existente sigue una cierta convención, debería seguirla. Además, algunas plataformas de lenguaje tienden a utilizar cierto esquema de nomenclatura. Por ejemplo, en Java, la mayoría del código usa nombres en camelCase, mientras que en PHP la mayoría utiliza guiones bajos.

Estos también pueden ser mezclados. Algunos desarrolladores prefieren utilizar guiones bajos para funciones de procedimiento y nombres de clase, pero utilizan camelCase para nombres de métodos de clase:

Entonces nuevamente, no hay un "mejor" estilo obvio. Sólo ser consistente.


6 - Principio DRY

DRY significa Don't Repeat Yourself - No se Repita a sí Mismo. También conocido como DIE: Duplication is Evil - Duplicar es Maligno.

El principio establece:

"Cada pedazo de conocimiento debe tener una representación única, inequívoca, autoritaria dentro de un sistema".

El propósito de la mayoría de las aplicaciones (o de los computadores en general) es automatizar tareas repetitivas. Este principio se debe mantener en todo el código, incluso en aplicaciones web. El mismo pedazo de código no debe repetirse una y otra vez.

Por ejemplo, la mayoría de las aplicaciones web consisten de muchas páginas. Es muy probable que estas páginas contengan elementos comunes. Los encabezados y los pies de página suelen ser los mejores candidatos para esto. No es una buena idea mantenerse copiando y pegando estos encabezados y pies de página en cada una de las páginas. Aquí vemos a Jeffrey Way explicando cómo crear plantillas en CodeIgniter.


7 - Evite la Anidación Profunda

Demasiados niveles de anidamiento pueden hacer que el código sea más difícil de leer y seguir.

Por motivos de legibilidad, es generalmente posible realizar cambios a su código para reducir el nivel de anidamiento:


8 - Limite la Longitud de Línea

Nuestros ojos están más cómodos al leer columnas altas y estrechas de texto. Esta es precisamente la razón por la que los artículos de periódico tienen este aspecto:

Es una buena práctica evitar escribir largas líneas horizontales de código.

Además si alguien tiene la intención de leer el código desde una ventana de terminal, como los usuarios de Vim, es una buena idea limitar la longitud de línea a unos 80 caracteres.


9 - Organización de Archivos y Carpetas

Técnicamente, podría escribir el código de una aplicación completo dentro de un solo archivo. Pero eso resultaría en una pesadilla para leer y mantener.

Durante mis primeros proyectos de programación, conocí acerca de la idea de crear "archivos incluidos". Sin embargo, todavía no estaba ni remotamente organizado.  He creado una carpeta "inc", con dos archivos en ella: db.php y functions.php. A medida que las aplicaciones crecían, el archivo de funciones también se hacía enorme e inmanejable.

Uno de los mejores enfoques es bien sea utilizar un framework o imitar su estructura de carpetas. Así es como se ve CodeIgniter:


10 - Nombres Temporales Consistentes

Normalmente, las variables deben ser descriptivas y contener una o más palabras. Pero esto no necesariamente aplica a variables temporales. Estas pueden ser tan cortas como de un solo carácter.

Es una buena práctica utilizar nombres coherentes para sus variables temporales que tengan el mismo tipo de rol. Estos son algunos de los ejemplos que tiendo a utilizar en mi código:


11 - Capitalizar Palabras Especiales de SQL

La interacción de bases de datos es una gran parte de la mayoría de las aplicaciones web. Si está escribiendo consultas SQL sin procesar, es una buena idea mantenerlas legibles también.

A pesar de que las palabras especiales y los nombres de funciones de SQL no distinguen entre mayúsculas y minúsculas, es una práctica común escribirlas en mayúsculas para distinguirlas de sus nombres de tabla y columna.


12 - Separación de Código y Datos

Este es otro principio que aplica a casi todos los lenguajes de programación en todos los entornos. En el caso del desarrollo web, los "datos" usualmente implican salida de HTML.

Cuando PHP fue lanzado por primera vez hace muchos años, fue visto principalmente como un motor de plantilla.  Era común tener grandes archivos HTML con unas pocas líneas de código PHP contenido en ellos. Sin embargo, las cosas han cambiado a través de los años y los sitios web se volvieron cada vez más dinámicos y funcionales. El código es ahora una gran parte de las aplicaciones web, y ya no es una buena práctica combinarlo con el HTML.

Usted bien puede aplicar el principio a su aplicación por sí mismo, o puede utilizar una herramienta de terceros (motores de plantilla, frameworks o CMS) y seguir sus convenciones.

Frameworks PHP Populares:

Motores de Plantilla Populares:

Sistemas de Manejo de Contenidos Populares


13 - Sintaxis Alterna Dentro de las Plantillas

Usted puede elegir no usar un elegante motor de plantilla y en lugar de esto utilizar PHP en línea simple en sus archivos de plantilla. Esto no viola necesariamente la "Separación de Código y Datos", siempre y cuando el código en línea esté directamente relacionado con la salida y sea legible. En este caso usted debería considerar el uso de la sintaxis alterna para las estructuras de control.

Aquí un ejemplo:

Esto le permite evitar un sinnúmero de llaves. Además, el código se ve y se siente similar a la forma en que HTML está estructurado y sangrado.


14 - Orientado a Objetos vs. Procedural

La programación orientada a objetos puede ayudarle a crear código bien estructurado. Pero eso no significa que usted necesite abandonar completamente la programación procedural. De hecho la creación de una mezcla de ambos estilos puede ser buena.

Los objetos se deben utilizar para representar datos, que generalmente están alojados en una base de datos.

Las funciones procedurales pueden ser utilizadas para tareas específicas que se pueden ejecutar independientemente.

15 - Lea Código Fuente Abierto

Los proyectos de código abierto se construyen con el aporte de muchos desarrolladores. Estos proyectos necesitan mantener un alto nivel de legibilidad de código para que el equipo pueda trabajar de una manera conjunta tan eficientemente como sea posible. Por lo tanto, es una buena idea navegar a través del código fuente de estos proyectos para observar lo que estos desarrolladores están haciendo.


16 - Refactorización de Código

Cuando usted "refactoriza", realiza cambios al código sin cambiar ninguna de sus funcionalidades. Usted puede pensar en esto como una "limpieza" con el fin de mejorar la legibilidad y la calidad.

Esto no incluye las correcciones de errores ni la adición de ninguna nueva funcionalidad. Usted puede refactorizar el código que haya escrito el día anterior mientras todavía está fresco en su cabeza, de manera que sea más legible y reutilizable cuando usted potencialmente lo revise dentro de dos meses. Como dice el lema: "Refactorice pronto, refactorice seguido."

Usted puede aplicar cualquiera de estas "mejores prácticas" de legibilidad de código durante el proceso de refactorización.

¡Espero que haya disfrutado de este artículo! ¿Me faltó algo? Hágamelo saber por medio de los comentarios.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.