Para Arduino

Un comentario, en programación, es un fragmento de texto que se incluye en el código para aportar información extra y explicaciones a las instrucciones escritas.

Los comentarios en programación son muy importantes, puesto que ayudan a comprender el código cuando no somos nosotros quienes lo hemos escrito o cuando lo retomamos después de algún tiempo.

En Arduino no es diferente. Incluir comentarios en los sketch nos ayudará a mantener nuestros proyectos en un futuro. Es una muy buena práctica comentar los sketch, así que acostúmbrate siempre a utilizar comentarios en Arduino.

¿Qué son los comentarios en Arduino?

Como ya mencioné al inicio del artículo, un comentario es un fragmento de texto que se incluye en el código del sketch para aportar información adicional.

Mira el siguiente sketch:

// DECLARACIONES
/*
Pin digital en el que está conectado el LED
*/
const int LED = 9; 

// CONFIGURACIÓN
/*
La función setup contiene toda la configuración inicial.
En este caso, el pin 9 se está configurando como salida. 
*/
void setup()
{
  pinMode(LED, OUTPUT);
}

// FUNCIÓN LOOP
/* Función principal. Se ejecutará de forma repetitiva.
Enciende y apaga el LED cada segundo:
  - digitalWrite(LED, HIGH): Enciende el LED
  - digitalWrite(LED, LOW): Apaga el LED
  - delay(1000): Genera un retraso de 1s (1000ms)
*/
void loop()
{
  digitalWrite(LED, HIGH);
  delay(1000); // Esperar 1000 ms
  digitalWrite(LED, LOW);
  delay(1000); // Esperar 100 ms
}

Todo lo que ves en verde son comentarios. Si te fijas, están escritos en lenguaje natural porque la finalidad es aportar explicaciones sobre el código del sketch.

Cuando el sketch se compila todos los comentarios se eliminan automáticamente al generar el ejecutable, porque no aportan nada para la ejecución, pero siempre permanecerán intactos en el fichero fuente, es decir, en el fichero con extensión .ino.

¿Cualquier texto que pongas en el sketch es un comentario? Pues no, hay una nomenclatura que debes respetar, sino el compilador no entenderá que se trata de un comentario y te devolverá un error.

Si te fijas en el sketch anterior, todos los comentarios van acompañados por estos caracteres: // o /* */. Esta es la forma en la que le indicamos al compilador que se trata de un comentario y debe ignorarlo.

A continuación vamos a ver los dos tipos de comentarios que existen en Arduino.

Comentarios de una línea en Arduino

Los comentarios de una línea, como su nombre indica, ocupan una única línea.

Para escribir comentarios de una línea en Arduino debes usar las dos barras inclinadas (//) seguidas del comentario.

Por ejemplo:

//esto es un comentario de una linea

//esto también es un comentario
pero si salto de línea esto dará error

En la línea 1 hay un comentario de una línea bien formado. Como puedes ver, la línea comienza con 2 barras inclinadas y a continuación está el comentario escrito con lenguaje natural.

En la línea 3 también hay un comentario bien formado, pero al haber un salto de línea al final, el resto del comentario para a la línea 4 y deja de estar en verde. Esto el compilador ya no lo considerará comentario, por lo que dará error.

Si necesitas escribir más de una línea de comentarios puedes incluir las 2 barras inclinadas al inicio de cada línea o usar comentarios de bloque, que los veremos en el siguiente punto.

Los comentarios de una línea pueden ser útiles para incluir una anotación sobre una instrucción de código concreta como puedes ver en el siguiente ejemplo:

void loop()
{
  digitalWrite(LED, HIGH);
  delay(1000); // Esperar 1000 ms
  digitalWrite(LED, LOW);
  delay(1000); // Esperar 100 ms
}

En las líneas 4 y 6 hay un fragmento de código (delay(1000);) y a continuación un comentario de una línea.

El compilador interpretará que debe ejecutar la instrucción delay(1000) e ignorar todo lo que hay después de las 2 barras inclinadas (// Esperar 1000 ms).

Como puedes comprobar, no es obligatorio que el comentario se encuentre al inicio de la línea, puedes colocarlos después de las instrucciones para incluir explicaciones adicionales. Lo único que no puedes hacer, con este tipo de comentarios, es saltar de línea. Para eso debes utilizar los comentarios de bloque, que los vamos a ver a continuación.

Comentarios de bloque en Arduino

Los comentario de bloque o multi-linea permiten incluir más de una línea en el comentario.

Este tipo de comentario es muy útil para documentar el código, puesto que permiten aportar explicaciones más extensas y detalladas que los comentarios de una sola línea.

Los comentarios de bloque comienzan con una barra inclinada y un asterisco (/*) y siempre se deben cerrar con un asterisco y una barra inclinada (*/).

Mira el siguiente ejemplo:

/*
Esto es un comentario de bloque
puesto que puedo escribir múltiples líneas
y no producirán ningún error.
*/

/*
Esto también es un comentario de bloque, aunque solo tenga una línea
*/

El primer bloque, que va de la línea 1 a la 5 es un comentario compuesto por varias líneas. Como puedes comprobar se abre y se cierra de forma correcta con /* */.

En el caso del segundo bloque, también se abre y se cierra de la misma forma, aunque el comentario solo tenga una línea. Esto significa que puedes utilizar este tipo de nomenclatura también para escribir comentarios de una sola línea sin ningún problema.

Recuerda siempre cerrar los comentarios de bloque porque el compilador no sabrá dónde termina el comentario y te devolverá un error de tipo unterminated comment.

Por otro lado, también debes tener cuidado con no solapar comentarios de bloque, porque la apertura y el cierre pueden no realizarse de forma correcta. Como en el siguiente ejemplo:

/*Esto es un comentario de bloque
/*Y esto es otro comentario dentro del anterior*/
Esto se supone que es parte del primer comentario pero va a dar error
*/

Como puedes comprobar, la última línea del comentario no se ve en verde porque el compilador interpreta el cierre de la línea 2, como el cierre del primer comentario abierto en la línea 1.

Ventajas de utilizar comentarios en Arduino

Acostúmbrate siempre a comentar tus sketch. Utiliza tanto comentarios de una línea como comentarios de bloque.

Se trata de una muy buena práctica que aporta grandes ventajas a tus proyectos.

• Mejoran la legibilidad del código: Los comentarios pueden ayudar a explicar el propósito de cada línea de código, lo que te facilitará la comprensión de tu propio código si necesitas retomarlo en el futuro. También será de gran ayuda a otros programadores que puedan entrar en el proyecto.
• Simplifican el mantenimiento del código: Ayudan a entender la lógica detrás de un fragmento de código, lo que facilita la corrección de errores, la implementación de mejoras y la realización de actualizaciones.
• Ayudan a documentar el código: Los comentarios pueden ayudar a documentar el código, lo que puede ser útil para futuras versiones o para que otras personas que necesiten usarlo puedan entenderlo.
• Facilitan el seguimiento de cambios en el código: Pueden ser útiles para marcar los cambios que se hayan realizado en el código, proporcionando una pista de los ajustes realizados y sus razones.

Mejores practicas para escribir comentarios en Arduino

Aquí te dejo algunas recomendaciones para escribir buenos comentarios en Arduino y que, además de ser descriptivos y claros, sean útiles y prácticos.

• Sé conciso y claro: Asegúrate de que los comentarios sean claros, brinden información relevante y sean concisos.
• Actualiza los comentarios: Mantén los comentarios actualizados para que reflejen los cambios en el código y siempre reflejen su funcionalidad real.
• Evita comentarios obvios: Los comentarios siempre deben aportar información adicional por lo que no debes escribir comentarios que repitan exactamente lo que hace el código.
• Comentarios de cabecera: Es útil tener un comentario de cabecera al principio de tu programa que explique en términos generales cuál es la finalidad del mismo.
• Uso de comentarios para depuración: Durante la depuración, puedes utilizar comentarios que desactiven temporalmente partes del código sin eliminarlas por completo.

¡Suscríbete a la newsletter y no te pierdas nada!

Te avisaré cuando publique nuevo contenido en paraarduino.com y en mi canal de YouTube (@ParaArduino).