SQL Comments: qué son y cómo crearlos

8min

Cuando estamos desarrollando una aplicación y trabajamos con sentencias SQL es importante ser cuidadosos, ya que se trata de un código delicado y a veces difícil de interpretar. En esos casos en los que las consultas se vuelven complejas, echar mano de los comentarios de SQL nos puede venir bien para documentar la lógica y facilitar el mantenimiento.

Índice

¿Qué son los SQL Comments?

El lenguaje SQL también tiene su manera de crear comentarios al código, como cualquier otro lenguaje de programación. SQL Comments no son más que los comentarios dentro del código SQL, es decir, fragmentos de texto que no afectan la ejecución de las consultas y sirven primariamente para documentar las consultas y ayudar a que cualquier persona consiga comprenderlas mejor.

En general los comentarios pueden ayudar al mantenimiento de las consultas o la depuración, aunque no siempre son buenos. En este artículo exploraremos los pros y contras de usarlos.

Tipos de comentarios SQL

Antes de empezar a ver la sintaxis para escribir los comentarios vamos a explicar los tipos que existen.

Comentarios de una sola línea

Son SQL Comments que afectan a toda una línea. Este tipo de comentarios se utilizan para anotar explicaciones breves.

Comentarios en línea

Son comentarios que aparecen en una línea de código SQL, al final de una instrucción. Los comentarios en línea se usan para comentar lo que se ha hecho en esa misma línea de código.

Comentarios en multilínea

Como su nombre indica, son comentarios que pueden abarcar varias líneas de código. Son usados para explicar bloques completos de código, permitiendo documentar de manera más extensa una consulta SQL.

¿Cómo escribir comentarios en SQL?

Ahora vamos a ver la sintaxis para escribir comentarios en el lenguaje SQL. Aunque luego veremos que cada dialecto de lenguaje SQL puede tener ligeras diferencias.

Uso del doble guión (–) para comentarios de una línea

Para los comentarios que se realizan en la misma línea, ya sea comentar una línea entera o comentar el final de la línea, se usa el doble guión. Todo lo que pongamos después de los dos guiones se tratará como un comentario.

Así pues, si queremos comentar una línea completa solamente tenemos que comenzar por los dos guiones.

-- Esto es un comentario de una línea

SELECT * FROM clientes;

Y si queremos comentar el final de una línea de código SQL podemos colocar los dos guiones y escribir el comentario a continuación.

SELECT * FROM clientes WHERE activo = 1; -- Filtra solo los clientes activos

Uso de /* … */ para comentarios en bloque

Luego tenemos los comentarios de bloque. Para escribir este tipo de SQL Comment que abarca varias líneas, se emplea una barra y un asterisco, cerrado de asterisco barra. En este caso la sintaxis es idéntica a la de otros lenguajes como Java o Javascript.

/*
Este comentario explica el siguiente bloque de código
que obtiene todos los clientes activos.
*/

SELECT * FROM clientes WHERE activo = 1;

Compatibilidad de los comentarios en MySQL, PostgreSQL y SQL Server

Como debes saber, el lenguaje SQL es un estándar, por lo que la mayoría de los sistemas gestores de bases de datos lo usan de manera muy similar. Sin embargo, a veces existen algunas diferencias que debemos de conocer. 

En el caso de los comentarios SQL en realidad no es así y todos los sistemas gestores más populares los soportan perfectamente, incluidos MySQL, PostgreSQL y SQL Server.

Solo como recomendación para ahorrarnos problemas, y también para mayor claridad en el código, recomendamos colocar un espacio después del inicio de un comentario con doble guión, ya que algunos sistemas gestores no son capaces de interpretar ese inicio de comentario si no tiene un espacio justo detrás.

Beneficios de usar SQL Comments

Los comentarios en el código pueden tener beneficios, que se dejan apreciar en mayor medida cuando el SQL que estamos desarrollando es especialmente complejo.

Mejora la legibilidad del código

Los comentarios nos ayudan a comprender el propósito de las consultas y la lógica que hemos usado para escribirlas. Pueden venir bien para el trabajo en equipo pero también para nosotros mismos cuando leamos el código pasados unos meses.

Obviamente, un simple «SELECT * FROM usuarios» no necesita comentarse, porque todo el mundo consigue interpretarlo de un vistazo rápido, pero si tenemos una consulta más compleja es muy probable que la podamos interpretar mejor si nos ofrecen algunos comentarios extra.

Por ejemplo mira la siguiente consulta:

/* Esta consulta obtiene la cantidad total de ventas por categoría 
   en los últimos 6 meses, excluyendo productos descontinuados */

SELECT c.nombre_categoria, SUM(v.cantidad) AS total_ventas
FROM ventas v
JOIN productos p ON v.producto_id = p.id
JOIN categorias c ON p.categoria_id = c.id
WHERE v.fecha >= DATE_SUB(CURDATE(), INTERVAL 6 MONTH)
AND p.estado != 'descontinuado'
GROUP BY c.nombre_categoria;

Sin el comentario al principio es muy probable que tuvieras que analizar los JOIN y pensar un rato antes de entender su propósito.

Facilita el mantenimiento y depuración

Los comentarios bien explicados permiten entender las consultas SQL y por tanto cuando tenemos que hacer mantenimiento sobre ellas es más fácil poder meterles mano sin miedo a romper alguna cosa o dejar de lado algún propósito de la consulta.

También permiten identificar rápidamente errores o partes del código que podrían requerir optimización.

Optimiza el trabajo en equipo

Como hemos dicho antes, los comentarios SQL proporcionan un contexto valioso a otros desarrolladores que puedan leer nuestro código y por tanto ayudan a que el equipo pueda comunicarse mejor al desarrollar las aplicaciones.

Evita la repetición de consultas complejas

Al documentar consultas avanzadas, se reduce la necesidad de analizarlas repetidamente y con ello se facilita la reutilización o la modificación de las consultas con otros parámetros.

Permite desactivar temporalmente partes del código

Si tenemos una sentencia SQL bien estructurada, podemos comentar una parte de la sentencia para evitar que se ejecute temporalmente, lo que puede venirnos bien para hacer pruebas durante la depuración del código.

Consejos para escribir comentarios SQL

Ahora vamos a ver algunos consejos útiles y buenas prácticas cuando introduces SQL Comments en tus consultas.

Sé claro y conciso

Todo comentario debe ser suficientemente claro, pero a la vez necesitas ser conciso para explicar el funcionamiento con pocas palabras. Si no eres capaz de hacerlo el comentario perderá su valor o incluso puede ocurrir que confunda más que ayude.

Usa un formato coherente

Mantén un formato uniforme en tus comentarios ya que facilitará la lectura y el mantenimiento del código. Cuando se trabaja en equipo los patrones de comentarios deben compartirse entre todos para que se usen siempre los mismos.

Actualiza los comentarios cuando modifiques el código

Muy importante: si has comentado una sentencia SQL y luego la actualizas en una fase de mantenimiento, también se deben actualizar los comentarios, para que expresen lo que está haciendo el código una vez actualizado.

Errores comunes en los comentarios de SQL

Ya para acabar vamos a presentar algunos errores comunes que cometen los desarrolladores al comentar las sentencias SQL.

Comentarios mal ubicados que generan errores de sintaxis

Si no ubicas los comentarios en el lugar correcto o usas mal la sintaxis para marcarlos es posible que tus sentencias dejen de funcionar o no lo hagan como se espera. 

Un error en tiempo de ejecución te puede alertar en muchos casos cuando un comentario SQL está mal realizado. Pero puede ser peor todavía cuando, por culpa de un comentario, ciertas partes de la consulta no se están teniendo en cuenta, sin que por ello se produzca un error. Este tipo de situaciones puede ser difícil de detectar, así que ten cuidado.

Exceso de comentarios innecesarios que saturan el código

Los comentarios deben usarse cuando realmente aporten un valor significativo. Si las sentencias son sencillas es muy fácil leerlas y entenderlas rápidamente. Para sentencias complejas entonces puede ser conveniente usarlos. 

Sin embargo, siempre tienes que ser conciso, ya que demasiados comentarios pueden dificultar la lectura del código, en lugar de facilitarla.

No actualizar comentarios al modificar el código SQL

Lo peor que puede ocurrir cuando pones comentarios en el código es que no expliquen con exactitud lo que están comentando. Llegar a esta situación es probable cuando modificas el código SQL de tu consulta y no te tomas el tiempo necesario para actualizar el comentario y expresar su nuevo funcionamiento.

Si el comentario no se actualiza puede ser un problema más que una ayuda porque puede inducir a errores de interpretación.

Fernán García de Zúñiga

Artículos relacionados

Productos relacionados: