Introducción a los comentarios en programación

Son muchos los detalles a los que debemos prestar atención mientras desarrollamos, tantos que en ocasiones relegamos un segundo plano a algunos como pueden ser los comentarios, el estilo del código u otros.

Comentarios en Programación

A pesar de que en un primer instante pueda parecer un asunto un tanto superficial, los comentarios en la programación son un tema muy interesante, no por su complejidad, sino porque un correcto uso de ellos puede marcar la diferencia en cuanto a limpieza, facilidad de comprensión del código y su mantenimiento.

Objetivo de los comentarios

Los comentarios, cuando hablamos de programación, son bloques de texto escritos en lenguaje natural que están incluidos dentro del código fuente, que el compilador ignora y que por norma general están destinados a que sea el programador el que los interprete.

El objetivo principal de un comentario es dejar constancia en el código fuente de la intención de un determinado bloque de código. Esto es especialmente útil cuando más de un programador tiene acceso al mismo código o para recordar en el futuro por qué tomamos determinada estrategia para el código al que hacemos referencia.

Existe también un segundo objetivo muy extendido y de gran utilidad que es para documentar el código. Siguiendo algunas reglas que varían en función de la herramienta, ciertos comentarios pueden ser interpretados por aplicaciones que generan documentación de manera automática. Algunos ejemplos de estas aplicaciones son Javadoc en Java o Doxygen en PHP.

Características de los comentarios

Así que dejando al margen del tema de la documentación, para que un comentario aporte todo el valor que se le presupone debe cumplir algunas características.

  1. Complementar al código. Un buen comentario debe transmitir la intención del programador, el concepto, el motivo, la estrategia, pero nunca traducir a lenguaje natural ni explicar el código que hemos escrito, eso ya lo sabe hacer la persona que lee el código.
  2. Ser claro y comprensible. Escribimos los comentarios para que otros, o nosotros mismos en el futuro, los lean, así que asegurémonos de que cuando lo hagan comprendan perfectamente el mensaje que les estamos transmitiendo. ¿Cuántas veces escribiste una nota que al leerla pasado cierto tiempo no eres capaz de entenderla?
  3. Ser conciso. No hace falta extendernos o explicar hasta el último detalle, cuanto más concisos seamos más fácil será comprenderlo e invertiremos menos tiempo en ello.

Profundizando en los comentarios

Realmente esta entrada no era más que una excusa para introducir y dar paso a otros artículos relacionados con los comentarios.

Estos artículos guardarán también cierta relación con una entrada que escribimos hace tan solo unas semanas atrás: ¿A qué huele el código fuente?, tratando el código oloroso y en la que hacíamos referencia a los comentarios como una posible fuente de olores.

Así que a continuación tenéis todas esas entradas que durante las próximas semanas iremos publicando:

  1. Comentarios a evitar
  2. Mantenimiento de comentarios
  3. Comentarios y nombres de elementos

Conclusión

Los comentarios, lejos de lo que pueda parecer cuando no se tiene la suficiente experiencia, son un tema que a pesar de su simplicidad pueden marcar la diferencia en nuestro código y al que merece la pena dedicarle cierto tiempo.

 

Contenido relacionado

Deja un comentario

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