Skip to content

Como ser un mejor programador – Comenta tu código.

Esta sera una mini serie de posts, algunos tal vez un poco cortos pero enfocados a un tema en especifico con la intención de ayudar a aquel que comienza a programar, o que ha programado solo en proyectos de la escuela, que haces y no vuelves a abrir jamas y que desea mejorar pero no sabe por donde empezar.


Disclaimer: Soy desarrollador .NET y mi día a día lo paso en Visual Studio, por lo que a lo largo de estos posts probablemente veras implementaciones especificas de Visual Studio, pero la idea general es valida sin importar el stack en el que desarrolles.


Hay una frase que escuche hace tiempo y que trato de seguir: “Comenta tu código como si la persona que lo fuera a mantener fuera un asesino serial que sabe donde vives”, creo que la idea queda muy clara.

Y no se trata de hacerle un favor a tus compañeros de equipo (de carrera o de trabajo) el hecho de mantener tu código limpio, ordenado y comentado es algo que debes de hacer para ti mismo. Por que mas temprano que tarde, si es que no te ha pasado ya, regresaras a ese código que escribiste hace meses, y deberás entenderlo.

Ahora, tampoco se trata de agregar un comentario por cada linea de código que escribiste, pero al menos debes de considerar escribir la descripción de cada método, para que sepas que es lo que hace a detalle sin tener que leer todo el método, ayuda el tener nombres descriptivos, pero es preferible que el método tenga un nombre corto (un par de palabras en base a la funcionalidad que cumple) y una descripción detallada a querer poner una descripción en el nombre del método.


En Visual Studio basta con escribir diagonal tres veces para que Visual Studio haga el comentario formateado de la descripción del método en cuestión. Dicho comentario formateado contiene no solo la descripción del método, si no la descripción de los parámetros (en caso de que el método tenga) y la descripción del resultado del método.

Utilizar esto nos ayuda ademas para la documentación de nuestro código, algo que veremos en un siguiente post.


En lo personal, trato de utilizar las descripciones en cada método que escribo, sobre todo cuando es funcionalidad especifica como manejar criptografia o hasheos, manejar imágenes, etc. Debo ser honesto y decir que no siempre escribo las descripciones en cuanto escribo el método, a veces es lo ultimo que hago antes de hacer un commit o bien, a veces después de hacer el commit y ver que lo olvide.

De ahí en fuera, solo uso comentarios en algunas ocasiones, principalmente cuando hago alguna operación compleja dejo un comentario del porque se realiza de la manera en la que lo hice. En ocasiones en bloques condicionales (if-else o switch) para ayudar a entender los casos que se manejan de manera mas sencilla y poder identificar si algo se me esta pasando.

Otro escenario que estoy comenzando a adoptar es en la corrección de bugs, esto para indicar el motivo de la notificación, notese que esto generalmente queda descrito en los task de la herramienta de planeación que uses (en mi caso VSTS o Jira), o incluso en los commits que solucionan los bugs, pero aun así, cuando trabajas en equipo es mas fácil que los demás vean el código y sepan por que se modifico.

Quiero hacer una aclaración, esto es en mi opinión, en lo que he visto en estos años de desarrollador, pero lo principal que tienes que tener en mente es que el lugar en el que trabajes probablemente tendrá una serie de reglas sobre como manejar esto (junto con otras cosas) llamadas Convenciones de código, en un próximo post de esta misma serie tocare este tema.

Pero por ahora, déjame un comentario y dime, ¿cual es tu opinión en cuanto a los comentarios?

Hasta la próxima.

Omar Martínez.

Be First to Comment

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *