Cách tạo chú thích (comment) trong SQL

SQL, viết tắt của Structured Query Language, là một ngôn ngữ mạnh mẽ để quản lý và thao tác với cơ sở dữ liệu quan hệ. Mặc dù các truy vấn SQL thoạt nhìn có thể khá dễ hiểu, việc thêm chú thích (comment) vào câu lệnh SQL sẽ giúp mã của bạn dễ đọc và dễ bảo trì hơn.

Trong hướng dẫn này, chúng ta sẽ xem cách thêm chú thích trong SQL để mã của bạn đơn giản và dễ đọc hơn.

Câu trả lời nhanh: Cách tạo chú thích trong SQL

Có ba cách để thêm chú thích vào truy vấn SQL của bạn:

1. Chú thích một dòng: Chú thích một dòng bắt đầu bằng cặp dấu gạch ngang --.

2. Chú thích nội tuyến: Chú thích nội tuyến bắt đầu bằng -- sau câu lệnh SQL trên cùng một dòng.

3. Chú thích nhiều dòng hay chú thích khối: Chú thích nhiều dòng bắt đầu bằng /* và kết thúc bằng */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Được hỗ trợ bởi

Vì sao chú thích SQL quan trọng?

Dưới đây là ba lý do chính khiến chú thích SQL quan trọng:

• Làm rõ mục đích của mã: Chú thích giải thích mục đích và logic của mã, giúp người khác và chính bạn dễ hiểu hơn khi xem lại sau này.
• Tăng cường làm việc nhóm: Chú thích hỗ trợ làm việc nhóm bằng cách ghi lại (document) mã cho các lập trình viên khác, giúp họ nắm bắt công việc của bạn.
• Hỗ trợ gỡ lỗi và tối ưu hóa: Chú thích giúp đơn giản hóa quá trình gỡ lỗi và tối ưu mã theo thời gian, giúp việc xác định và khắc phục sự cố dễ quản lý hơn.

Các loại chú thích trong SQL

Tùy theo nhu cầu và sở thích, có ba cách để thêm chú thích trong các script SQL.

Chú thích một dòng

Nếu chú thích của bạn gói gọn trong một dòng, hãy dùng cặp dấu gạch ngang. Thông thường, bạn sẽ đặt những chú thích như vậy ở phía trên khối mã liên quan để cung cấp ngữ cảnh.

--select the department name from the department table
SELECT dept_name
FROM employees.departments;Được hỗ trợ bởi

Chú thích nội tuyến

Như có thể thấy trong ví dụ sau, chú thích một dòng và chú thích nội tuyến trong SQL dùng cùng cú pháp và về bản chất là giống nhau; sự khác biệt nằm ở vị trí và cách đặt. Chú thích nội tuyến thường được dùng để giải thích một phần cụ thể của truy vấn.

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;
Được hỗ trợ bởi

Chú thích nhiều dòng hoặc chú thích khối

Bạn có thể dùng chú thích nhiều dòng trong SQL để thêm các ghi chú dài trên nhiều dòng. Để thêm chú thích nhiều dòng, bao nội dung của bạn giữa /* và */. Trình thông dịch SQL sẽ bỏ qua mọi văn bản nằm giữa /* và */.

/*
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;
Được hỗ trợ bởi

Thực hành tốt nhất khi viết chú thích SQL

Để đảm bảo chú thích của bạn vừa ngắn gọn vừa giàu thông tin xuyên suốt codebase, điều quan trọng là tuân theo các thực hành tốt nhất. Hãy cùng xem một số hướng dẫn bên dưới. 

Rõ ràng và dễ đọc

Tránh dùng các thuật ngữ quá phức tạp hoặc quá kỹ thuật trong chú thích. Việc này giúp chú thích rõ ràng, súc tích để bất kỳ ai cũng có thể hiểu, ngay cả những người chưa quen với codebase.

Bổ sung thông tin liên quan

Đảm bảo thông tin bạn cung cấp chính xác và liên quan trực tiếp đến đoạn mã được mô tả. Nó nên giải thích lý do đằng sau logic phức tạp. Tránh đưa thông tin nhạy cảm vào chú thích, như mật khẩu và khóa API.

Cập nhật thường xuyên

Chú thích lỗi thời có thể gây hiểu lầm và làm tăng nợ kỹ thuật. Vì vậy, bạn nên rà soát và cập nhật chú thích khi cập nhật mã để phản ánh những thay đổi mới nhất.

Tránh trùng lặp

Chú thích không nên chỉ lặp lại những gì mã đang làm. Thay vào đó, chú thích nên giải thích “vì sao” phía sau mã – mục đích hoặc bối cảnh không thể hiện ngay từ chính mã.

Các sai lầm thường gặp khi viết chú thích SQL

Việc chú thích mã SQL của bạn cực kỳ quan trọng để giữ mọi thứ có tổ chức và dễ hiểu, đặc biệt khi bạn phải quay lại mã sau vài tháng. Nhưng ngay cả với ý định tốt nhất, bạn vẫn dễ mắc phải những cái bẫy khiến chú thích rối rắm hơn là hữu ích. Dưới đây là một số lỗi thường gặp cần tránh khi viết chú thích SQL:

Chú thích mơ hồ hoặc gây hiểu lầm

Hãy viết chú thích ngắn gọn, rõ ràng, mang lại giá trị cho người đọc. Chú thích không rõ ràng hoặc không chính xác còn tệ hơn là không có chú thích.

Lạm dụng chú thích

Dù chú thích hữu ích, việc chú thích quá mức có thể khiến mã khó đọc và khó bảo trì. Hãy tập trung giải thích mục đích cấp cao và những khía cạnh không hiển nhiên của mã.

Hãy xem một ví dụ chưa tốt:

Chú thích trong một truy vấn SQL. Ảnh: Tác giả.

Như có thể thấy, vì các biến của chúng ta có tên rõ ràng, chú thích chỉ lặp lại mã mà không cung cấp thêm ngữ cảnh hay giải thích mục đích.

Phong cách chú thích không nhất quán

Phong cách không nhất quán gây xao nhãng và khiến mã khó đọc hơn. Để tránh điều này, hãy dùng một phong cách chú thích nhất quán trong toàn bộ codebase. 

• Viết hoa: Duy trì quy tắc viết hoa nhất quán giúp mã của bạn dễ đọc và dễ hiểu.
• Dấu câu: Kết thúc mọi chú thích bằng dấu chấm có thể là một thói quen tốt, nhưng không bắt buộc. Mục tiêu chính là tính nhất quán.
• Định dạng: Bằng cách đặt ra hướng dẫn rõ ràng cho việc dùng chú thích khối và chú thích nội tuyến, bạn đảm bảo tính nhất quán.

Thiếu ngữ cảnh

Ví dụ sau bao gồm mô tả cấp cao về mục đích của mã SQL: "Truy xuất đơn hàng khách hàng cho báo cáo." Dù chính xác, nó thiếu ngữ cảnh cần thiết để người đọc hiểu đầy đủ mã.

/*
* 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;
Được hỗ trợ bởi

Để cải thiện chú thích, chúng ta có thể cập nhật để bao gồm nhiều chi tiết hơn.

/* 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;
Được hỗ trợ bởi

Các cách nâng cao khi dùng chú thích SQL

Bên cạnh việc tăng tính dễ đọc, chú thích SQL còn hỗ trợ quá trình viết mã. Phần này khám phá các cách dùng nâng cao của chú thích SQL, bao gồm nhúng siêu dữ liệu, gỡ lỗi mã SQL và tạm thời vô hiệu hóa mã. Những kỹ thuật này giúp đơn giản hóa việc viết mã, giúp bạn quản lý và xử lý sự cố các script SQL hiệu quả hơn.

Nhúng siêu dữ liệu

Bạn có thể dùng chú thích để nhúng siêu dữ liệu về mã SQL, như tên tác giả và ngày tạo hoặc ngày chỉnh sửa.

/*
Author: DataCamp
Date: 2024-05-28
Purpose: Retrieve employees' credentials for their record
*/
SELECT emp_no, first_name, last_name
FROM employees.employees
Được hỗ trợ bởi

Gỡ lỗi mã SQL

Bạn có thể comment một số phần mã SQL để cô lập và kiểm tra các phần cụ thể. Điều này giúp bạn xác định chính xác vị trí có thể phát sinh vấn đề.

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;
Được hỗ trợ bởi

Tạm thời vô hiệu hóa mã

Bạn có thể tạm thời vô hiệu hóa mã SQL bằng chú thích một dòng (--) hoặc chú thích nhiều dòng trong SQL (/* ... */). Bằng cách này, bạn giữ lại mã trong truy vấn mà không thực thi nó, điều này hữu ích khi chỉ muốn kiểm thử một số phần cụ thể của mã SQL.

SELECT column1, column2
FROM table1
WHERE condition1
/*
AND condition2
OR condition3
*/
Được hỗ trợ bởi

Những lầm tưởng và hiểu sai

Dù được sử dụng rộng rãi, vẫn tồn tại một vài lầm tưởng và hiểu sai dai dẳng về chú thích trong SQL.

Lời kết

Mặc dù có vẻ nhỏ bé trong phát triển SQL, chú thích có thể cải thiện mã và giúp nó dễ hiểu hơn. Bằng cách viết chú thích rõ ràng và có cấu trúc tốt, các nhà phát triển có thể đảm bảo mã SQL của họ vẫn dễ tiếp cận ngay cả nhiều năm sau khi được tạo ra lần đầu.

Nếu bạn mới bắt đầu hành trình SQL, nắm vững các kiến thức cơ bản qua khóa học như SQL Fundamentals có thể giúp bạn sớm hiểu được tầm quan trọng của việc chú thích. Khi tiến xa hơn, đạt được SQL Associate Certification sẽ xác nhận kỹ năng của bạn và cho thấy bạn có thể viết mã rõ ràng, có tài liệu đầy đủ. Để nâng cao kỹ năng hơn nữa, khóa Intermediate SQL đi sâu vào các truy vấn phức tạp hơn, nơi chú thích chi tiết có thể được dùng cho các mục đích như gỡ lỗi.