Pular para o conteúdo principal
InicioTutoriaisSQL

Como criar comentários no SQL

Analise três métodos para adicionar comentários no SQL: comentários de linha única, comentários de várias linhas e comentários em linha usando a seguinte sintaxe: --, /* e */.
Actualizado 30 de jul. de 2024  · 5 min leer

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  

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;

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;

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;

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:

Exemplo de comentário ruim em SQL

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;

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;

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

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;

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

Mitos e concepções errôneas

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

Mito nº. Mito Realidade
1 Os comentários SQL tornam a execução mais lenta. O mecanismo SQL ignora os comentários, portanto, eles não têm impacto sobre o desempenho.
2 Os comentários SQL tornam o código mais difícil de ler e entender. Comentários bem escritos têm o efeito oposto: Eles podem tornar o código mais fácil de ler.
3 Os comentários SQL são úteis apenas para iniciantes. Até mesmo desenvolvedores experientes podem se beneficiar de comentários bem escritos, especialmente quando trabalham em consultas complexas ou revisam o código depois de muito tempo.

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.

Perguntas frequentes

Como posso garantir que meus comentários SQL sejam compreensíveis para os novos membros da equipe?

Use comentários claros e descritivos que expliquem a finalidade e a funcionalidade do código de forma eficaz.

Como os comentários do SQL ajudam na depuração?

Os comentários SQL podem ajudar na depuração, fornecendo contexto de código adicional. Isso ajuda a identificar e corrigir erros com mais eficiência.

Os comentários SQL são necessários para todas as consultas SQL?

Não, os comentários SQL não são necessários para todas as consultas SQL. No entanto, eles são altamente recomendados para consultas complexas e para consultas que são difíceis de entender sem contexto adicional.

Há alguma ferramenta ou interface específica que tenha restrições adicionais aos comentários?

Algumas ferramentas, como o SQLPlus, podem ter restrições adicionais aos comentários. Por exemplo, o SQLPlus não permite uma linha em branco dentro de um comentário de várias linhas.

É verdade que somente os iniciantes precisam escrever comentários em SQL?

Não, mesmo os desenvolvedores experientes se beneficiam de comentários bem escritos, especialmente quando trabalham em consultas complexas ou revisitam o código depois de muito tempo.

Temas

Aprenda SQL com a DataCamp

Certificação disponível

Course

Introdução ao SQL

2 hr
727K
Aprenda a criar e consultar bancos de dados relacionais usando SQL em apenas duas horas.
See DetailsRight Arrow
Start Course
Ver maisRight Arrow
Relacionado
SQL Jobs Header

blog

O SQL é uma linguagem de programação?

O SQL é considerado uma linguagem de programação? Analisamos os vários fatores a serem considerados e para que o idioma é usado.
Sejal Jaiswal's photo

Sejal Jaiswal

11 min

tutorial

Tutorial do Insert Into SQL

A instrução "INSERT INTO" do SQL pode ser usada para adicionar linhas de dados a uma tabela no banco de dados.
DataCamp Team's photo

DataCamp Team

3 min

tutorial

SELEÇÃO de várias colunas no SQL

Saiba como selecionar facilmente várias colunas de uma tabela de banco de dados em SQL ou selecionar todas as colunas de uma tabela em uma consulta simples.
DataCamp Team's photo

DataCamp Team

3 min

tutorial

Exemplos e tutoriais de consultas SQL

Se você deseja começar a usar o SQL, nós o ajudamos. Neste tutorial de SQL, apresentaremos as consultas SQL, uma ferramenta poderosa que nos permite trabalhar com os dados armazenados em um banco de dados. Você verá como escrever consultas SQL, aprenderá sobre
Sejal Jaiswal's photo

Sejal Jaiswal

21 min

tutorial

FUNÇÃO SQL COUNT()

COUNT() permite que você conte o número de linhas que correspondem a determinadas condições. Saiba como usá-lo neste tutorial.
Travis Tang 's photo

Travis Tang

3 min

tutorial

Como comentar um bloco de código em Python

O uso de comentários é fundamental para trabalhar efetivamente com Python. Neste breve tutorial, aprenda a comentar um bloco de código em Python.
Adel Nehme's photo

Adel Nehme

3 min

See MoreSee More