Como criar comentários no SQL

SQL, que significa Structured Query Language (Linguagem de consulta estruturada), é uma linguagem avançada para gerenciar e manipular bancos de dados relacionais. Embora as consultas SQL possam parecer autoexplicativas à primeira vista, adicionar comentários às instruções SQL pode melhorar a legibilidade e a manutenção do seu código.

Neste tutorial, veremos como adicionar comentários no SQL para tornar seu código mais simples e fácil de ler.

A resposta rápida: Como criar comentários no SQL

Há três maneiras de adicionar comentários às suas consultas SQL:

1. Comentários de uma linha: Os comentários de linha única começam com -- hífens duplos.

2. Comentários em linha: Os comentários em linha começam com -- após a instrução SQL na mesma linha.

3. Comentários de várias linhas ou comentários em bloco: Os comentários de várias linhas começam com /* e terminam com */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Tecnologia

Por que os comentários do SQL são importantes?

Aqui estão três motivos principais pelos quais os comentários do SQL são importantes:

• Esclarecendo o objetivo do código: Os comentários explicam a finalidade e a lógica do código, facilitando o entendimento de outras pessoas e de você mesmo quando for revisar o código posteriormente.
• Aprimorar o trabalho em equipe: Os comentários facilitam o trabalho em equipe ao documentar o código para outros desenvolvedores, ajudando-os a compreender o seu trabalho.
• Auxiliando na depuração e otimização: Os comentários simplificam o processo de depuração e otimização do código ao longo do tempo, tornando mais fácil identificar e corrigir problemas.

Tipos de comentários SQL

Dependendo de suas necessidades e preferências, há três maneiras de adicionar comentários em scripts SQL.

Comentários de linha única

Se o seu comentário couber em uma única linha, use hífens duplos. Normalmente, você colocaria esses comentários acima do bloco de código relevante para fornecer contexto.

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

Comentários em linha

Como podemos ver no exemplo a seguir, os comentários de linha única e em linha no SQL usam a mesma sintaxe e são essencialmente os mesmos; a diferença está em onde e como eles são colocados. Os comentários em linha tendem a ser usados para explicar uma parte específica da 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;
Tecnologia

Comentários de várias linhas ou comentários em bloco

Você pode usar comentários de várias linhas no SQL para adicionar comentários mais longos em várias linhas. Para adicionar comentários de várias linhas, coloque seu texto entre /* e */. O interpretador SQL ignorará qualquer texto entre /* e */.

/*
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;
Tecnologia

Práticas recomendadas para escrever comentários SQL

Para garantir que seus comentários sejam concisos e informativos em toda a base de código, é importante que você siga as práticas recomendadas. Vamos analisar algumas das diretrizes abaixo. 

Clareza e legibilidade

Evite usar termos muito complexos ou técnicos em seus comentários. Isso garantirá que eles sejam claros e concisos para que qualquer pessoa possa entender, mesmo aquelas que não estão familiarizadas com a base de código.

Adicione informações relevantes

Certifique-se de que as informações que você fornece sejam precisas e diretamente relevantes para o código que elas descrevem. Ele deve explicar o raciocínio por trás da lógica complexa. Evite incluir informações confidenciais nos comentários, como senhas e chaves de API.

Atualize regularmente

Comentários desatualizados podem induzir ao erro e contribuir para o débito técnico. É por isso que você deve revisar e atualizar seus comentários à medida que atualiza o código para refletir as alterações mais recentes.

Evite a redundância

Os comentários não devem simplesmente reafirmar o que o código está fazendo. Em vez disso, os comentários devem explicar o "porquê" por trás do código - o propósito ou o contexto que não é imediatamente aparente no próprio código.

Erros comuns em comentários SQL

Comentar seu código SQL é muito importante para manter as coisas organizadas e compreensíveis, especialmente se você tiver que revisar seu código meses depois. Mas mesmo com as melhores intenções, é fácil cair em armadilhas que tornam seus comentários mais confusos do que úteis. Aqui estão alguns erros comuns que você deve evitar ao escrever comentários SQL:

Comentários ambíguos ou enganosos

Escreva comentários concisos e não ambíguos que agreguem valor ao leitor. Comentários pouco claros ou imprecisos são piores do que nenhum comentário.

Código com excesso de comentários

Embora os comentários sejam úteis, o excesso de comentários pode tornar o código mais difícil de ler e manter. Tente se concentrar em explicar o propósito de alto nível e quaisquer aspectos não óbvios do código.

Vamos dar uma olhada em um exemplo ruim:

Comentário em uma consulta SQL. Imagem do autor.

Como podemos ver, como nossas variáveis tinham nomes explícitos, os comentários apenas reafirmaram o código sem fornecer contexto adicional ou explicar sua finalidade.

Estilo de comentário inconsistente

Estilos inconsistentes causam distração e dificultam a leitura do código. Para evitar isso, use um estilo de comentário consistente em toda a sua base de código. 

• Capitalização: Manter a capitalização consistente facilita a leitura e a compreensão do seu código.
• Pontuação: Terminar todos os comentários com pontos finais pode ser uma boa prática, mas não é uma regra rígida. O principal objetivo é a consistência.
• Formatação: Ao definir diretrizes claras para o uso de comentários em bloco versus comentários em linha, você garante a consistência.

Falta de contexto

O exemplo a seguir inclui uma descrição de alto nível da finalidade do nosso código SQL: "Recuperar pedidos de clientes para relatórios." Embora preciso, ele não tem o contexto necessário para ajudar o leitor a entender completamente o 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;
Tecnologia

Para melhorar nosso comentário, podemos atualizá-lo para incluir mais detalhes.

/* 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;
Tecnologia

Usos avançados de comentários SQL

Além de melhorar a legibilidade, os comentários SQL também ajudam no processo de codificação. Nesta seção, exploramos os usos avançados dos comentários SQL, incluindo a incorporação de metadados, a depuração do código SQL e a desativação temporária do código. Essas técnicas ajudam a simplificar a codificação, facilitando o gerenciamento e a solução de problemas dos scripts SQL de forma eficaz.

Incorporação de metadados

Você pode usar comentários para incorporar metadados sobre o código SQL, como o nome do autor e a data de criação ou modificação.

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

Depuração de código SQL

Você pode comentar seções do seu código SQL para isolar e testar partes específicas. Isso pode ajudar você a identificar onde pode estar ocorrendo um problema.

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

Desativar temporariamente o código

Você pode desativar temporariamente o código SQL usando comentários de linha única (--) ou comentários de várias linhas no SQL (/* ... */). Dessa forma, você pode manter o código na consulta sem executá-lo, o que pode ser útil para testar apenas partes específicas do seu código SQL.

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

Mitos e concepções errôneas

Apesar de seu uso generalizado, há alguns mitos e equívocos persistentes sobre os comentários SQL.

Considerações finais

Embora possa parecer insignificante para o desenvolvimento de SQL, os comentários podem aprimorar o código e facilitar a compreensão. Ao escrever comentários claros e bem estruturados, os desenvolvedores podem garantir que seu código SQL permaneça acessível mesmo anos após sua criação inicial.

Se você está apenas começando sua jornada com o SQL, entender o básico por meio de um curso como o SQL Fundamentals pode ajudá-lo a compreender a importância dos comentários desde o início. À medida que você progride, a obtenção de uma certificação SQL Associate valida suas habilidades e mostra que você pode escrever códigos claros e bem documentados. Para aprimorar ainda mais suas habilidades, o SQL intermediário se aprofunda em consultas mais complexas, nas quais comentários detalhados podem ser usados para depuração.