Hace unos días estaba leyendo un artículo de la Revista Software Gurú, en dicho artículo el autor comenta acerca de la necesidad de hacer código comentado. Él menciona que se debe comentar el código por 4 razones, y cito:
- Garantías de un producto final de la mayor calidad.
- Seguridad en el cumplimiento de los tiempos y costos del proyecto.
- La confianza de que se determina el mejor proceso para desarrollar su producto.
- Que el producto contará con la escalabilidad necesaria para seguir creciendo.
Si bien, coincido con todos los puntos que menciona el autor, me parece que hay también otro punto importante a destacar, y es: por salud mental nuestra.
Con lo anterior me refiero a que siempre debemos hacer lo posible por dejar claro, al menos, para qué sirve una función, un método, o una clase; porque, créanlo o no, esto nos ahorrará muchísimo tiempo y dolores de cabeza a nuestro Yo del futuro, ya que en muchas ocasiones nos veremos en la necesidad de modificar programas que hicimos cuando recién iniciábamos en la programación, y muy seguramente cuando vean sus programas antiguos se preguntarán: «En serio yo hice eso?», «Qué significa este parámetro?«, «Qué demonios es todo este embrollo?«. Pero tranquilos, si cuando ven su código antiguo algo parecido a estas preguntas rondan por su cabeza, eso quiere decir que han ido mejorando y creciendo en conocimientos, preocúpense cuando vean tus programas viejos y crean que siguen siendo lo máximo.
No a la documentación tediosa
Pero bueno, lo anterior no era el punto. La idea que les quiero compartir es que, al igual que la gran mayoría de ustedes: Odio documentar. Y es que cada vez que alguien menciona la palabra documentación, inmediatamente recordamos nuestras clases de Fundamentos de la Programación, así como las interminables noches donde teníamos que hacer n cantidad de diagramas de flujo, UML, requerimientos, y además, comentar casi cada linea de nuestro código, el cual si no era hecho todo por nosotros mismos, se convertía en un verdadero viacrucis.
Sí bien ese sería el deber ser de cada uno de nuestros proyectos, no siempre (o más bien casi nunca) tenemos el tiempo y el dinero para invertir en un proceso de documentación tan tedioso. Por lo tanto, y debido a varias experiencias propias, he implementado una forma muy fácil y rápida (que quizá ya existe desde hace mucho) de comentar mis programas, y esta es sólo colocando descripciones claras y concisas de lo que se refiere cada bloque, sección, función, etc. Esta forma de hacer mis comentarios me han ayudado muchísimo en momentos en que tengo que modificar programas viejos, y de paso, otros colegas varias veces me han agradecido por dejarles siempre el código comentado, así que con esto matamos varios pájaros de un sólo tiro y sin invertir demasiado tiempo.
Mis Tips para Comentar el Código
- Es lo primero que hay que hacer después de definir una función, método o clase; o bien, después de alguna estructura de control. Es decir, inmediatamente después de que pongo algún if, for, o function, lo que hago es hacer un pequeño comentario de lo que hace ese bloque.
- Nunca trato de hacer una tesis en cada comentario, por el contrario trato de resumir lo más posible la función principal del bloque y eso es lo que pongo en el comentario.
- Al comentar una función, siempre pongo las definiciones de los parámetros (si los hay). Por ejemplo, la siguiente función:
12345678function muestra($param1, $param2) {//Esta es una función de muestra para probar los comentarios//param1: el primer parámetro que recibe la función//param2: esta es otra descripción del parámetro$saludo = 'Hola Comentarios :)';return $saludo;}
Realmente no es nada complejo hacer de los comentarios parte de su programación, y reitero, les puede ayudar mucho para futuros cambios o para cuando quieran relevar sus programas.
Espero que les sea de utilidad, y sí, espero sus comentarios.