如何在 SQL 中添加注释

SQL（Structured Query Language，结构化查询语言）是一种用于管理和操作关系型数据库的强大语言。虽然很多 SQL 查询乍看之下不言自明，但在 SQL 语句中添加注释可以提升代码的可读性与可维护性。

在本教程中，我们将演示如何在 SQL 中添加注释，让您的代码更简洁、更易读。

快速上手：如何在 SQL 中添加注释

在 SQL 查询中添加注释有三种方式：

1. 单行注释： 单行注释以 -- 双连字符开头。

2. 行内注释： 行内注释在同一行的 SQL 语句之后以 -- 开头。

3. 多行注释或块注释： 多行注释以 /* 开始，以 */ 结束。

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  技术支持

为什么 SQL 注释很重要？

以下是 SQL 注释重要性的三个关键原因：

• 阐明代码意图： 注释解释代码的目的与逻辑，便于他人以及将来的您回看时理解代码。
• 提升协作效率： 注释为团队其他开发者提供文档化说明，帮助他们理解您的工作。
• 有助于调试与优化： 注释使后续调试与优化过程更顺畅，更容易定位与修正问题。

SQL 注释的类型

根据您的需求与偏好，您可以用以下三种方式在 SQL 脚本中添加注释。

单行注释

如果注释内容可在一行内说明，使用双连字符。通常您会把这类注释放在相关代码块上方，用于提供上下文。

--select the department name from the department table
SELECT dept_name
FROM employees.departments;技术支持

行内注释

如下例所示，SQL 中的单行注释与行内注释使用相同语法，本质相同；区别在于放置的位置与方式。行内注释通常用于解释查询中的某个特定部分。

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;
技术支持

多行注释或块注释

当需要跨多行添加较长注释时，可使用多行注释。将注释文本包裹在 /* 与 */ 之间。SQL 解释器会忽略 /* 与 */ 之间的所有文本。

/*
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;
技术支持

编写 SQL 注释的最佳实践

为确保整个代码库中的注释既简洁又信息充分，请遵循最佳实践。下面我们来回顾一些建议。

清晰与可读

避免在注释中使用过于复杂或过度技术化的术语。确保注释清楚、精炼，即便对不熟悉代码库的人也能读懂。

补充相关信息

确保您提供的信息准确且与所描述的代码直接相关，应当解释复杂逻辑背后的思路。避免在注释中包含敏感信息，如密码和 API 密钥。

定期更新

过时的注释会误导读者并增加技术债。因此在更新代码时请同步检查并更新注释，以反映最新变更。

避免冗余

注释不应只是重复代码在做什么。相反，注释应解释代码背后的“原因”——那些仅从代码本身不易立即看出的目的或上下文。

SQL 注释中的常见错误

为 SQL 代码添加注释对于保持条理与可理解性至关重要，尤其当您在数月后回看代码时更是如此。但即使出于好意，也很容易踩坑，让注释变得比有用更混乱。以下是编写 SQL 注释时应避免的一些常见错误：

含糊或误导性的注释

编写简洁明确、对读者有价值的注释。含糊或不准确的注释比没有注释更糟。

过度注释

注释虽有帮助，但过度注释会降低代码的可读性与可维护性。请重点解释高层目的及代码中不明显的部分。

来看一个不佳的示例：

SQL 查询中的注释。作者供图。

如上所示，由于变量命名已经足够明确，注释只是重复了代码，没有提供额外上下文或解释其目的。

注释风格不一致

风格不一致会分散注意力并降低代码可读性。为避免这种情况，请在整个代码库中使用一致的注释风格。

• 大小写： 保持一致的大小写有助于提升代码的可读性与理解度。
• 标点： 为所有注释加句号是一种不错的做法，但并非硬性规定。关键在于保持一致。
• 格式： 通过明确规定何时使用块注释与行内注释，可以确保风格一致。

缺乏上下文

下面这个示例给出了我们 SQL 代码目的的高层描述：“为报表检索客户订单”。虽然准确，但缺少足够的上下文，读者仍难以充分理解代码。

/*
* 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;
技术支持

要改进这条注释，我们可以补充更多细节。

/* 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;
技术支持

SQL 注释的高级用法

除了提升可读性，SQL 注释也能助力编码过程。本节将探讨 SQL 注释的进阶用法，包括嵌入元数据、调试 SQL 代码以及临时禁用代码。这些技巧有助于简化开发，使您更高效地管理与排查 SQL 脚本。

嵌入元数据

您可以使用注释嵌入有关 SQL 代码的元数据，例如作者姓名、创建或修改日期。

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

调试 SQL 代码

您可以将 SQL 代码的某些部分注释掉，以便隔离并测试特定片段，从而帮助定位问题所在。

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;
技术支持

临时禁用代码

您可以使用单行注释（--）或多行注释（/* ... */）临时禁用 SQL 代码。这样可在查询中保留代码但不执行，对于仅测试 SQL 代码的特定部分非常有用。

SELECT column1, column2
FROM table1
WHERE condition1
/*
AND condition2
OR condition3
*/
技术支持

常见迷思与误解

尽管被广泛使用，关于 SQL 注释仍存在一些挥之不去的迷思与误解。

结语

尽管在 SQL 开发中看似不起眼，注释却能让代码更好、更易理解。通过编写清晰且结构合理的注释，开发者可以确保自己的 SQL 代码在多年之后仍然易于阅读与维护。

如果您刚开始学习 SQL，通过类似 SQL Fundamentals 的课程打好基础，有助于您从一开始就重视注释。随着进阶，获得 SQL Associate Certification 能验证您的技能，并表明您能够编写清晰、文档完善的代码。若想进一步提升能力，Intermediate SQL 将深入探讨更复杂的查询场景，在这些场景中，详尽注释可用于调试等用途。