Cómo crear comentarios en SQL

SQL, que significa Lenguaje de Consulta Estructurado, es un potente lenguaje para gestionar y manipular bases de datos relacionales. Aunque las consultas SQL pueden parecer autoexplicativas a primera vista, añadir comentarios en las sentencias SQL puede mejorar la legibilidad y la capacidad de mantenimiento de tu código.

En este tutorial, veremos cómo añadir comentarios en SQL para que tu código sea más sencillo y fácil de leer.

La respuesta rápida: Cómo crear comentarios en SQL

Hay tres formas de añadir comentarios a tus consultas SQL:

1. Comentarios de una sola línea: Los comentarios de una sola línea empiezan con -- guiones dobles.

2. Comentarios en línea: Los comentarios en línea comienzan con -- después de la sentencia SQL en la misma línea.

3. Comentarios multilínea o comentarios en bloque: Los comentarios multilínea comienzan con /* y terminan con */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  

¿Por qué son importantes los comentarios SQL?

He aquí tres razones clave por las que los comentarios SQL son importantes:

• Aclarar la finalidad del Código: Los comentarios explican la finalidad y la lógica del código, facilitando su comprensión a los demás y a ti mismo cuando revises tu código más adelante.
• Mejorar el trabajo en equipo: Los comentarios facilitan el trabajo en equipo al documentar el código para otros desarrolladores, ayudándoles a comprender tu trabajo.
• Ayuda a la depuración y optimización: Los comentarios simplifican el proceso de depuración y optimización del código a lo largo del tiempo, haciendo más manejable la identificación y corrección de problemas.

Tipos de comentarios SQL

Dependiendo de tus necesidades y preferencias, hay tres formas de añadir comentarios en los scripts SQL.

Comentarios de una sola línea

Si tu comentario cabe bien en una sola línea, utiliza guiones dobles. Lo normal es que coloques estos comentarios encima del bloque de código correspondiente para proporcionar contexto.

--select the department name from the department table
SELECT dept_name
FROM employees.departments;

Comentarios en línea

Como podemos ver en el siguiente ejemplo, los comentarios de una sola línea y en línea en SQL utilizan la misma sintaxis y son esencialmente iguales; la distinción radica en dónde y cómo se colocan. Los comentarios en línea suelen utilizarse para explicar una parte concreta de la consulta.

SELECT DISTINCT title -- It excludes duplicate titles using the DISTINCT keyword.
FROM employees.titles
ORDER BY title ASC -- The results are sorted alphabetically by the 'title' column.
LIMIT 10;

Comentarios multilínea o comentarios en bloque

Puedes utilizar comentarios multilínea en SQL para añadir comentarios más largos en varias líneas. Para añadir comentarios multilínea, encierra tu texto entre /* y */. El intérprete SQL ignorará cualquier texto encerrado entre /* y */.

/*
This query retrieves the employee number, first name, last name, and gender
from the 'employees' table in the 'employees' database.
It filters the results only to include male employees, limiting to 4 rows.
*/
SELECT emp_no, first_name, last_name, gender
FROM employees.employees
WHERE employees.employees.gender = 'M'
LIMIT 4;

Buenas prácticas para escribir comentarios SQL

Para garantizar que tus comentarios sean concisos e informativos en todo tu código base, es importante seguir las mejores prácticas. Repasemos a continuación algunas de las directrices. 

Claridad y legibilidad

Evita utilizar términos demasiado complejos o técnicos en tus comentarios. Esto garantizará que sean claras y concisas para que cualquiera pueda entenderlas, incluso quienes no estén familiarizados con el código base.

Añade información relevante

Asegúrate de que la información que proporcionas es exacta y directamente relevante para el código que describe. Debe explicar el razonamiento que hay detrás de la lógica compleja. Evita incluir información sensible en los comentarios, como contraseñas y claves API.

Actualiza regularmente

Los comentarios obsoletos pueden inducir a error y contribuir a la deuda técnica. Por eso debes revisar y actualizar tus comentarios a medida que actualizas el código para reflejar los últimos cambios.

Evita la redundancia

Los comentarios no deben limitarse a repetir lo que hace el código. En cambio, los comentarios deben explicar el "por qué" del código: el propósito o el contexto que no se desprende inmediatamente del propio código.

Errores comunes en los comentarios SQL

Comentar tu código SQL es superimportante para mantener las cosas organizadas y comprensibles, sobre todo si tienes que volver a revisar tu código meses después. Pero incluso con las mejores intenciones, es fácil caer en trampas que hacen que tus comentarios sean más confusos que útiles. Aquí tienes algunos errores comunes que debes evitar al escribir comentarios SQL:

Comentarios ambiguos o engañosos

Escribe comentarios concisos y sin ambigüedades que aporten valor al lector. Los comentarios poco claros o inexactos son peores que la ausencia de comentarios.

Comentar demasiado el código

Aunque los comentarios son útiles, comentar demasiado puede hacer que el código sea más difícil de leer y mantener. Intenta centrarte en explicar la finalidad de alto nivel y cualquier aspecto no evidente del código.

Veamos un mal ejemplo:

Comentario en una consulta SQL. Imagen del autor.

Como podemos ver, como nuestras variables tenían nombres explícitos, los comentarios se limitaban a reformular el código sin proporcionar contexto adicional ni explicar su finalidad.

Estilo de comentario incoherente

Los estilos incoherentes distraen y dificultan la lectura del código. Para evitarlo, utiliza un estilo de comentarios coherente en todo tu código base. 

• Capitalización: Mantener unas mayúsculas y minúsculas coherentes hace que tu código sea más fácil de leer y comprender.
• Puntuación: Terminar todos los comentarios con puntos puede ser una buena práctica, pero no es una norma estricta. El objetivo principal es la constancia.
• Formato: Al definir directrices claras para utilizar comentarios en bloque frente a comentarios en línea, garantizas la coherencia.

Falta de contexto

El siguiente ejemplo incluye una descripción de alto nivel de la finalidad de nuestro código SQL: "Recuperar pedidos de clientes para informes". Aunque es preciso, carece del contexto necesario para ayudar al lector a comprender plenamente el código.

/*
* Retrieve employees' data for reporting
*/
SELECT e.first_name, e.last_name, s.salary
FROM employees.employees e
JOIN employees.salaries s ON e.emp_no = s.emp_no
WHERE s.salary > 150000
ORDER BY s.salary DESC;

Para mejorar nuestro comentario, podemos actualizarlo para incluir más detalles.

/* Retrieve employees' names and salaries where salary is above $150,000
as part of the monthly HR reporting process.
*/
SELECT e.first_name, e.last_name, s.salary
FROM employees.employees e
JOIN employees.salaries s ON e.emp_no = s.emp_no
WHERE s.salary > 150000
ORDER BY s.salary DESC;

Usos avanzados de los comentarios SQL

Además de mejorar la legibilidad, los comentarios SQL también ayudan en el proceso de codificación. En esta sección, exploramos los usos avanzados de los comentarios SQL, incluyendo la incrustación de metadatos, la depuración de código SQL y la desactivación temporal de código. Estas técnicas ayudan a agilizar la codificación, facilitando la gestión y la resolución de problemas de tus scripts SQL de forma eficaz.

Incrustar metadatos

Puedes utilizar comentarios para incrustar metadatos sobre el código SQL, como el nombre del autor y la fecha de creación o modificación.

/*
Author: DataCamp
Date: 2024-05-28
Purpose: Retrieve employees' credentials for their record
*/
SELECT emp_no, first_name, last_name
FROM employees.employees

Depurar código SQL

Puedes comentar secciones de tu código SQL para aislar y probar partes concretas. Esto puede ayudarte a identificar dónde puede estar ocurriendo un problema.

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;

Desactivar temporalmente el código

Puedes desactivar temporalmente el código SQL utilizando comentarios de una sola línea (--) o comentarios de varias líneas en SQL (/* ... */). De este modo, puedes mantener el código en la consulta sin ejecutarlo, lo que puede ser útil para probar sólo partes específicas de tu código SQL.

SELECT column1, column2
FROM table1
WHERE condition1
/*
AND condition2
OR condition3
*/

Mitos e ideas falsas

A pesar de su uso generalizado, existen algunos mitos y conceptos erróneos persistentes sobre los comentarios SQL.

Reflexiones finales

Aunque pueda parecer insignificante para el desarrollo de SQL, los comentarios pueden mejorar el código y facilitar su comprensión. Escribiendo comentarios claros y bien estructurados, los desarrolladores pueden asegurarse de que su código SQL siga siendo accesible incluso años después de su creación inicial.

Si acabas de empezar tu andadura en SQL, comprender los fundamentos a través de un curso como Fundamentos de SQL puede ayudarte a captar la importancia de los comentarios desde el principio. A medida que progresas, la obtención de una Certificación de Asociado SQL valida tus conocimientos y demuestra que puedes escribir código claro y bien documentado. Para mejorar aún más tus habilidades, SQL Intermedio profundiza en consultas más complejas en las que se pueden utilizar comentarios detallados para cosas como la depuración.