11 Consejos para escribir código limpio

Los desarrolladores gastan la mayor parte de su tiempo leyendo código, esto podemos resolverlo usando una guía de estilos para escribir software, y así tener un código limpio.

Diseño web
Lectura de 9 minutos
12 feb. 2020
11 Consejos para escribir código limpio

Los desarrolladores escribimos código (software) que ejecuten las máquinas y que leen las personas. Poder desarrollar software de una manera ágil y, sobre todo, que podamos mantener y escalar con el tiempo, necesitamos seguir una serie de guías que nos permita entender lo que escribimos. Siempre debemos pensar en que el código lo estaremos leyendo frecuentemente para encontrar problemas, para mejorar rendimiento o para agregar nuevas características.

Cuantas veces has revisado un código tuyo o de un compañero y has quedado totalmente confundido con lo que hace? Es más seguido de lo que crees, y no solo te pasa a ti.

Por estas razones, Robert C. Martin (prestigioso desarrollador desde el año 1970) escribió un manual de estilo para el desarrollo ágil de software llamado Código limpio.

Antes de darte un resumen, debo decirte que estos son consejos y no quieren imponerte una estructura rígida o inflexible. Yo siempre trato de utilizar las prácticas que, a mi modo de trabajo y a modo de trabajo de mi equipo, nos funcionen mejor. Sin embargo, piensa que estos consejos son usados por la gran mayoría de equipos de desarrollo del mundo.

Aquí te doy los consejos que más me llaman la atención para usar en el desarrollo de software:

1. Nombres con sentido

Nombra tus variables, constantes y funciones con un sentido holístico. Es decir, deben indicar por qué existe, qué hace y cómo se usa.

Mira este código:

int p; // Pago en dólares

Ese nombre utilizado p no está informando nada acerca de lo que hace la variable y, aunque tiene un comentario, tendríamos que estar haciendo scroll para recordar de qué trata.

Mejor:

int paymentInUSD;

Así tendremos claro qué hace esta variable: Almacena el valor de pago en dólares. Y no tenemos qué recurrir al comentario.

2. Nombres que se puedan pronunciar

En el libro no lo menciona, pero es altamente aceptado, sugerido y hasta obligado el uso del inglés para nombrar las variables, constantes y funciones. Esto es un estándar de la industria. Ahora, aunque tu no sepas inglés, los nombres deben poderse pronunciar. Te daré un ejemplo más claro:

date genymdhms;

Nota: ejemplo sacado directamente del libro.

La variable anterior no se puede mensionar en ningún lenguaje (español, inglés, aleman, etc). Son siglas que recordarla completamente o pronunciarlas será un verdadero dolor de cabeza. Así que sabiendo el objetivo de la variable (en este casso es la fecha exacta de generación del proceso) podemos cambiarla a:

date generationTimestamp;

3. Nombres que se puedan buscar

Si nombramos nuestras variables con una sola letra, será muy dificil hacer un Ctrl+f y buscar. En inglés la letra más usada es la e y en español la a, así que imaginense utilizar una sola letra y buscarla en el código. Verán todo el IDE o editor de código resaltando todas las letras.

4. Uso de abreviaciones

El libro recomienda no usar abreviaciones. Sin embargo, existen algunas abreviaciones que son tan comunes que tienen total sentido. Por ejemplo: source podríamos cambiarlo por src, imagepor img, entre otros. Por qué? Porque src, img y otras abreviaciones son ampliamente utilizadas, ejemplo:

<img src="path" alt="ejemplo de abreviaciones">

Observa cómo los desarrolladores ya estamos familiarizados con estas abreviaciones y son muy fáciles de entender.

5. Variables de una sola letra

Ya dijimos que no deben usar variables de una sola letra. Pero... como toda regla, existen sus excepciones:

for (int i = 0; i < 10; i++) {

Por qué nos permitimos usar una letra como nombre de variable en el anterior ejemplo? Bueno, porque el contexto nos permite entender que la variable i está actuando como un índice. Incluso podemos tener variables de una sola letra en funciones o métodos que son muy cortos:

public String sayHello(n string) {
  return "Hello " + n
}

En este ejemplo, n indica el nombre de la persona a la que se va a saludar. es fácil de entender y no hay que preocuparse con el uso de la variable en otro contexto. Sin embargo, hay equipos de programadores que prefieren:

public String sayHello(name string) {
  return "Hello " + name
}

Cuál prefieres tu?

6. Las funciones deben hacer una sola cosa

Es normal que mientras programamos, vamos escribiendo todo lo que tiene que hacer nuestro software. Pero en ocasiones las funciones (o métodos) se vuelven gigantes. Cuando lo lees, vas revisando que hay cosas que deberían estar en otras funciones (o métodos) más pequeños que serán llamados por tu función principal, así que podrás utilizar el refrán Divide y vencerás.

Ejemplo:

func burbleSort(numbers []int) {
  for i:=1; i < len(numbers); i++ {
   for j:=0; j < len(numbers)-1; j++ {
    if numbers[i] > numbers[j] {
     numbers[i], numbers[j] = numbers[j], numbers[i]
    }
   }
  }
}

Nota: El anterior código está escrito en Go.

¿No sabes Go? Mira nuestro curso de Go desde cero 👉https://ed.team/cursos/go

En el anterior código, la función burbleSort tiene demasiadas cosas que hacer, así que quitemosle algunas responsabilidades:

func burbleSort(numbers []int) []int {
  for i:=1; i < len(numbers); i++ {
   exchange(numbers, i)
  }
}
func exchange(numbers []int, i int) {
  for j:=0; j < len(numbers)-1; j++ {
   if numbers[i] > numbers[j] {
    numbers[i], numbers[j] = numbers[j], numbers[i]
   }
  }
}

Mucho mejor, ahora la función delegó el intercambio de posiciones a otra función. Tal vez podríamos dividirla aún más. Pero te lo dejo de tarea a ti.

7. Escribir código es como escribir un libro

Cuando escribas código, debes pensar en que al leerlo debes poder hacerlo como si estuvieras leyendo un libro. Con un orden, sabiendo que cada capítulo está enfocado a lograr un objetivo pequeño y al leer todo el libro habrás entendido el objetivo general.

8. Las funciones no deben tener efectos secundarios

Ya lo dijimos antes, pero lo repito: Las funciones deben hacer una sola cosa y la deben hacer bien.

// BAD
func isValidPayment(payment, coursePrice int) bool {
  if payment == coursePrice {
   createInvoice()
   return true
  }
  return false
}
// GOOD
func isValidPayment(payment, coursePrice int) bool {
  return payment == coursePrice
}

Observa cómo la primera función está mal porque además de validar si el pago del curso es correcto, crea una nueva factura de compra. Hay que quitarle esa responsabilidad y la función solo debe validar si el pago es correcto.

10. Haz testing!

Aún no haces test de tu código? Entonces lo estás haciendo mal. Aquí te dejo un curso que te ayuda a entender metodologías TDD: https://ed.team/cursos/metodologias-tdd

Hay muchas razones para hacer testing de tu código: Refactorización, mejora de rendimiento, corrección de bugs, etc. Pero para el tema de código limpio, hacer testing te permite dividir tu aplicación de forma correcta, haciendo que las funciones/métodos cumplan con una sola función, te ayuda a desacoplar tus clases/estructuras de acoplamientos innecesarios, etc.

11. Comentarios

Dejé este tema de los comentarios de último porque he visto muchas reviews del libro donde han malinterpretado el uso de los comentarios.

El libro sugiere que no uses comentarios. Pero, las reviews que he visto del libro han sido extremistas al decir que jamás se deben usar. Eso no es cierto, lo que dice el libro es que los comentarios de deben usar siempre y cuando agreguen valor al código.

Ejemplo de comentarios inútiles:

var dayOfMonth int // día del mes
func validateUser(u user) bool { // Valida el usuario
return value // retorna el valor
// Cambio de código hecho por Fulano de tal el 08/08/2008

Ejemplo de comentarios útiles:

// calculateOneByOne calcula los registros de manera individual.
// Debe usarse con cuidado ya que el rendimiento de esta función
// puede afectar seriamente el proceso de facturación del mes
func calculateOneByOne() {

El anterior comentario es útil porque le informa al desarrollador que hay que utilizarlo con cuidado ya que tiene un proceso que consume muchos recursos.

Lo importante es que si se decide realizar un comentario, es porque es útil debido a que expresa de una mejor manera lo que el código no puede expresar.

Conclusión

Existen muchas buenas prácticas para mejorar tu rendimiento como desarrollador, entre ellas es usar un código limpio en tus proyectos para que puedas leerlo fácilmente y para que otros también lo puedan leer y entender.

Si conoces más recomendaciones de este libro que te sirven en tu día a día, por favor coméntalo.

Nos vemos en un próximo post.

Si estás aquí es porque te interesa programar de forma correcta, si quieres seguir avanzado en tu carrera tenemos más de 150 cursos, seguro que más de uno está entre tus objetivos 👉 https://ed.team/cursos

Avatar

Alexys Lozada

@alexyslozadaVer perfil

Developer 🚀/ Speaker / Consultor / #Gopher / Educator / CTO @EDteamlat / Coorganizer #GDG & #GCDC Bogotá / Comparto conocimento en http://youtube.com/alexyslozada

Comentarios de los usuarios

JC
Juan Carlos Castillo Aycachi

@juancarloscastilloaycachi

Muy buen artículo, yo aún no termino de leer el libro, pero coincido en lo de los comentarios, claramente dice que de preferencia no darles uso, pero hay situaciones que lo ameritan. Yo cada vez trato de mejorar la legibilidad de mi código, me queda mucho por delante, ya que cuando reviso algún proyecto antiguo(o actual) me da vergüenza saber que yo escribí eso

Avatar
José Camilo Rodríguez Vera

@josecamilorodriguezvera

Excelente, más aún para personas como yo que empieza en este mundo; éstas publicaciones nos ayudan muchísimo

JM
Jhonatan Moncada

@jhonatanmoncada

Muy buen articulo y resumen del libro , muchas gracias.

Recuerda iniciar sesión para comentar este articulo

Cursos recomendados

Sass Desde Cero

Sass Desde Cero

Avatar

Alvaro Felipe

5

4.9

CSS Grid

CSS Grid

Avatar

Alvaro Felipe

5

0.0

Flexbox y Grid

Flexbox y Grid

Avatar

Alvaro Felipe

5

4.8