Cómo comentar código y adaptarnos a las buenas prácticas

Cómo comentar código y adaptarnos a las buenas prácticas

¡Hola Geekalt42ros!

Nos vamos a empezar a meter con situaciones polémicas que los desarrolladores vivimos todos los días. Comentar código es una acción que nos toma mucho tiempo en ocasiones, ya que los comentarios tienen diferente público: Otros programadores, Gerentes, o nosotros mismos.

Vamos a sonar muy atrevidos con esto pero, ¿Es necesario describir cada función, método o atributo? ¿Nuestros comentarios aportan algo a nuestro código? Porque una cosa es comentar nuestro código, y otra es que cuando el lector lea los comentarios, realmente entienda cómo funciona nuestro código.

Alguna vez leí en un libro (Clean Code – Robert C. Martin): “La razón por la que comentamos nuestro código, es porque no somos capaces de expresar programando lo que queremos decir” Esto, es la mera neta amigos.

No estamos diciéndoles que dejen de comentar su código. Claro que es importante hacerlo, pero nosotros opinamos que hay que evitar ante todo que nuestro código sea redundante, que haga ruido al momento de leer o comentarios que funcionen como banners casi publicitarios, como para separar regiones. Nuestros comentarios son válidos siempre y cuando expliquen la intención de nuestro código, más no expliquen lo que hace nuestro código. Don’t repeat yourself.

Imagínense que les piden realizar un proyecto en el trabajo o en la escuela, y que la única regla para desarrollar el proyecto es no incluir ningún comentario, y que el gerente o profesor entienda el código sin problemas.

Lo que tenemos que hacer (y es algo muy básico, que mucha gente viene arrastrando desde que empezó a programar), ¡Es darle nombres con sentido a nuestras variables, métodos, atributos o clases! Es absurdo encontrarnos todavía con variables que parecen que las escribió un niño de primaria (como popó, megazord, etc.). En nuestra opinión, los únicos nombres para variables a los que les damos chance de existir son [x, y, z, i, j, k. {variables de formulas}], pero fuera de eso, tenemos que empezar a nombrar mejor nuestro código.

Si se nos pidiera realizar un programa que administrara citas para el consultorio de un doctor, lo más natural es empezar un bosquejo muy minimalista del sistema: Debe incluir una manera para agregar citas, borrar citas, editar citas, borrar citas en un periodo de tiempo, agregar clientes, etc., y tal vez empecemos de la manera correcta haciéndo métodos bonitos.

El código se tiene que leer como si se estuviera contando una historia. Si otra persona que no haya visto nuestro código lo lee, y es capaz de entenderlo, estamos completamente del otro lado, nuestro código relata una historia de manera exitosa.

Aunque los nombres de nuestros métodos o variables sean largos, algo así como createAppointment, editAppointment, verifyIfPatientExists, existsAnUserWithThreeChilds, existsANotPayedAppointmentInCertainMonth, por lo menos al leerlos, sabemos qué se está evaluando sólo con código, aunque ciertamente siempre es buen momento para cambiar los nombres si aún no queda muy claro el código, o si hay una manera de reducir su longitud. Con esto se reduce la necesidad de comentarios largos encima de nuestros métodos: #In this method, we evaluate if there’s a user who has not payed an appointment in a certain month, que inclusive nosotros sabemos, hemos hecho comentarios mucho más largos.

Sabemos que hay muchos estilos para programar, y obviamente todos somos libres para hacer con nuestro código lo que queramos, pero tal vez llenar nuestro código de comentarios no sea la mejor idea. Los comentarios pueden hasta ser tediosos, y no hay necesidad de leer en un comentario lo que podemos leer en un código. 🙂

Si les gustó nuestro post, compartanlo en sus redes sociales. Aceptamos cualquier opinión aquí en los comentarios y en nuestros correos: geekalt42@gmail.com; lguitarras0594@gmail.com.

¡Happy coding! 😀

Written by Alberto Romero

Software developer intern @VoxFeed. Experiencia con Java, C#, desarrollo para Android y algunas tecnologías web como Golang, Python, Javascript y los tipicos de front end que ya se los saben de memoria. Me encanta la música y me gustan los videojuegos (especialmente DotA). Abierto a debate, conversaciones espontáneas y #random.

Deja un comentario

A %d blogueros les gusta esto: