SQL Comments: qué son y cómo crearlos

Cuando trabajamos con bases de datos, escribir un código claro, comprensible y mantenible es tan importante como que funcione correctamente. En ese caso, los comentarios SQL (o SQL comments) tienen un papel fundamental. Aunque no son ejecutados por la base de datos, los comentarios ayudan a documentar, explicar decisiones, y facilitar el trabajo. Los comentarios en SQL son una herramienta sencilla, pero poderosa. 

En esta guía te explicamos todo lo que necesitas saber para usarlos bien: qué tipos existen, cómo se escriben y qué errores debes evitar.

¿Qué es un comentario SQL?

Un comentario SQL es como una nota que se agrega en el código y puede servir para, aclarar qué hace una orden, avisar de algo raro o, simplemente, para tomar notas personales o para otros programadores. Al igual que en muchos lenguajes, estas notas no cambian nada del código final, ya que la base de datos las pasa por alto cuando se pone en marcha. 

Agregar estas notas en el código es algo positivo, ya que hace que se pueda entender mejor, ayuda a trabajar junto a equipos de programación y facilita el entender por qué de cada consulta, paso o función.

Tipos de comentarios SQL

En SQL existen dos formas principales de escribir comentarios, que también forman parte del lenguaje de marcado que utilizamos en front‑end (HTML):

1. Comentario de línea (single-line)

Es un tipo de comentario que comienza con dos guiones – -. Todo lo que escribas después en la misma línea será ignorado por el motor SQL.

SELECT * FROM empleados; -- Selecciona todos los empleados

Este tipo es ideal para añadir aclaraciones rápidas junto a una línea de código.

2. Comentario de bloque (multi-line o block comment)

Los comentarios en bloque de código se delimitan con /* para abrir y */ para cerrar. Todo lo que esté dentro de ese bloque será tratado como comentario, lo cual permite escribir anotaciones más largas o explicar secciones completas del código.

/*
Este bloque de código realiza
un filtrado de empleados activos
en el departamento de ventas
*/
SELECT * FROM empleados
WHERE activo = TRUE AND departamento = 'Ventas';

Este estilo es especialmente útil cuando se documentan procedimientos almacenados, funciones complejas o scripts largos.

¿Por qué deberías usar comentarios en SQL?

Usar comentarios en tus consultas no solo es una buena práctica, es una muestra de profesionalismo. Aquí tienes algunas razones para incluirlos en tu flujo de trabajo:

• Mejora la comprensión del código: especialmente útil cuando trabajas en equipo o si vas a revisar el código después de un tiempo.
  
• Facilita el mantenimiento: permite identificar rápidamente qué hace cada parte de una consulta compleja.
  
• Sirve como documentación: puedes anotar decisiones técnicas o reglas de negocio que justifican determinados filtros o joins.
  
• Ayuda en la depuración: puedes “comentar” líneas de código para probar consultas sin eliminarlas.
  

Errores comunes que debes evitar

1. Abusar de los comentarios: si necesitas comentar cada línea, tal vez tu consulta es demasiado compleja y deberías dividirla o simplificarla.
2. Incluir comentarios irrelevantes o ambiguos: comentarios como — prueba o — para ver qué pasa no aportan nada.
3. Olvidar limpiar comentarios de prueba: sobre todo si contienen datos sensibles o pruebas de seguridad.
4.  Anidar comentarios de bloque: recuerda que /* */ no se puede incluir dentro de otro bloque, generará un error de sintaxis.

Casos útiles para usar comentarios

Explicar una subconsulta compleja:

/* Obtenemos los productos con ventas superiores al promedio */
SELECT nombre FROM productos WHERE ventas > (
  SELECT AVG(ventas) FROM productos
);

Documentar funciones o stored procedures:

/*
  Función: calcular_descuento
  Entrada: precio original
  Salida: precio con descuento aplicado
*/

Desactivar condiciones temporalmente:

SELECT * FROM pedidos
WHERE fecha > '2024-01-01'
/* AND estado = 'entregado' */
ORDER BY fecha DESC;

Mejores prácticas al crear SQL comments

1. Sé claro y directo: Evita comentarios demasiado genéricos. Es mejor explicar por qué se hace algo que simplemente qué hace la línea (eso ya lo dice el código).
   
2. Evita lo obvio: No hace falta comentar cada línea si el código es legible. Por ejemplo, un SELECT * FROM clientes; no necesita un comentario que diga “selecciona todos los clientes”.
   
3. Actualiza los comentarios: Un gran error es mantener comentarios desactualizados que ya no reflejan lo que hace el código. Eso genera confusión y errores.
   
4. Utiliza comentarios para explicar decisiones: Si haces una optimización, una excepción o una consulta poco común, explica por qué. Esto será de gran ayuda para otros desarrolladores (o para ti mismo en unos meses).
   
5. No abuses del comentario en bloque: Aunque son útiles, los bloques demasiado largos pueden dificultar la lectura del código. Úsalos con criterio.

Comentar tus consultas SQL no es una obligación, pero sí una de las mejores prácticas para escribir código limpio, entendible y mantenible. Saber cuándo, cómo y por qué comentar te ahorrará tiempo, errores y confusión en cualquier proyecto que uses bases de datos.

Recuerda: el mejor código no es solo el que funciona, sino el que puede entender cualquiera del equipo (incluido tú mismo en seis meses).