Cara Membuat Komentar di SQL

SQL, singkatan dari Structured Query Language, adalah bahasa yang kuat untuk mengelola dan memanipulasi basis data relasional. Meskipun kueri SQL mungkin terlihat jelas sekilas, menambahkan komentar dalam pernyataan SQL dapat meningkatkan keterbacaan dan kemudahan pemeliharaan kode Anda.

Dalam tutorial ini, kita akan melihat cara menambahkan komentar di SQL agar kode Anda lebih sederhana dan mudah dibaca.

Jawaban Singkat: Cara Membuat Komentar di SQL

Ada tiga cara untuk menambahkan komentar ke kueri SQL Anda:

1. Komentar Satu Baris: Komentar satu baris diawali dengan tanda hubung ganda --.

2. Komentar Inline: Komentar inline diawali dengan -- setelah pernyataan SQL pada baris yang sama.

3. Komentar Multibaris atau Blok: Komentar multibaris dimulai dengan /* dan diakhiri dengan */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Didukung oleh

Mengapa Komentar SQL Penting?

Berikut tiga alasan utama mengapa komentar SQL penting:

• Menjelaskan Tujuan Kode: Komentar menerangkan tujuan dan logika kode, sehingga memudahkan orang lain dan diri Anda sendiri saat meninjau kode di kemudian hari.
• Meningkatkan Kolaborasi Tim: Komentar mempermudah kerja tim dengan mendokumentasikan kode untuk pengembang lain, membantu mereka memahami pekerjaan Anda.
• Membantu Debugging dan Optimasi: Komentar menyederhanakan proses debugging dan optimalisasi kode seiring waktu, sehingga lebih mudah mengidentifikasi dan memperbaiki masalah.

Jenis-jenis Komentar SQL

Bergantung pada kebutuhan dan preferensi Anda, ada tiga cara untuk menambahkan komentar dalam skrip SQL.

Komentar satu baris

Jika komentar Anda cukup dalam satu baris, gunakan tanda hubung ganda. Umumnya, komentar seperti ini diletakkan di atas blok kode terkait untuk memberikan konteks.

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

Komentar inline

Seperti terlihat pada contoh berikut, komentar satu baris dan komentar inline di SQL menggunakan sintaks yang sama dan pada dasarnya serupa; perbedaannya terletak pada tempat dan cara penempatannya. Komentar inline cenderung digunakan untuk menjelaskan bagian tertentu dari kueri.

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;
Didukung oleh

Komentar multibaris atau blok

Anda dapat menggunakan komentar multibaris di SQL untuk menambahkan komentar yang lebih panjang dalam beberapa baris. Untuk menambahkan komentar multibaris, tempatkan teks Anda di antara /* dan */. Interpreter SQL akan mengabaikan teks apa pun yang berada di antara /* dan */.

/*
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;
Didukung oleh

Praktik Terbaik untuk Menulis Komentar SQL

Agar komentar Anda tetap ringkas dan informatif di seluruh basis kode, penting untuk mematuhi praktik terbaik. Mari tinjau beberapa pedoman di bawah ini. 

Kejelasan dan keterbacaan

Hindari penggunaan istilah yang terlalu rumit atau terlalu teknis dalam komentar Anda. Ini akan memastikan komentar jelas dan ringkas sehingga siapa pun dapat memahaminya, bahkan yang tidak familiar dengan basis kode.

Tambahkan informasi yang relevan

Pastikan informasi yang Anda berikan akurat dan langsung relevan dengan kode yang dijelaskan. Komentar sebaiknya menjelaskan alasan di balik logika yang kompleks. Hindari menyertakan informasi sensitif dalam komentar, seperti kata sandi dan kunci API.

Perbarui secara berkala

Komentar yang usang dapat menyesatkan dan menambah utang teknis. Karena itu, tinjau dan perbarui komentar saat Anda memperbarui kode agar mencerminkan perubahan terbaru.

Hindari redundansi

Komentar tidak boleh sekadar mengulang apa yang dilakukan kode. Sebaliknya, komentar harus menjelaskan "mengapa" di balik kode – tujuan atau konteks yang tidak langsung terlihat dari kode itu sendiri.

Kesalahan Umum dalam Penulisan Komentar SQL

Memberi komentar pada kode SQL Anda sangat penting untuk menjaga kerapian dan keterbacaan, terutama jika Anda harus meninjau ulang kode setelah berbulan-bulan. Namun meski dengan niat baik, mudah terjebak dalam kesalahan yang membuat komentar justru membingungkan. Berikut beberapa kesalahan umum yang perlu dihindari saat menulis komentar SQL:

Komentar yang ambigu atau menyesatkan

Tulis komentar yang ringkas dan tidak ambigu yang memberikan nilai bagi pembaca. Komentar yang tidak jelas atau tidak akurat lebih buruk daripada tidak ada komentar sama sekali.

Terlalu banyak komentar

Meskipun komentar membantu, memberi komentar berlebihan dapat membuat kode lebih sulit dibaca dan dipelihara. Fokuslah menjelaskan tujuan tingkat tinggi dan aspek kode yang tidak langsung terlihat.

Mari kita lihat contoh yang kurang baik:

Komentar dalam kueri SQL. Gambar oleh Penulis.

Seperti terlihat, karena variabel kami memiliki nama yang eksplisit, komentar hanya mengulangi kode tanpa memberikan konteks tambahan atau menjelaskan tujuannya.

Gaya komentar yang tidak konsisten

Gaya yang tidak konsisten mengganggu dan membuat kode lebih sulit dibaca. Untuk menghindarinya, gunakan gaya komentar yang konsisten di seluruh basis kode Anda. 

• Huruf kapital: Menjaga konsistensi kapitalisasi membuat kode lebih mudah dibaca dan dipahami.
• Tanda baca: Mengakhiri semua komentar dengan tanda titik bisa menjadi kebiasaan yang baik, namun bukan aturan baku. Tujuan utamanya adalah konsistensi.
• Pemformatan: Dengan menetapkan pedoman yang jelas untuk penggunaan komentar blok versus komentar inline, Anda memastikan konsistensi.

Kurang konteks

Contoh berikut menyertakan deskripsi tingkat tinggi tentang tujuan kode SQL kita: "Mengambil pesanan pelanggan untuk pelaporan." Meskipun akurat, ini kurang konteks yang diperlukan agar pembaca benar-benar memahami kodenya.

/*
* 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;
Didukung oleh

Untuk memperbaiki komentar, kita dapat memperbaruinya agar mencakup lebih banyak detail.

/* 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;
Didukung oleh

Penggunaan Lanjutan Komentar SQL

Selain meningkatkan keterbacaan, komentar SQL juga membantu dalam proses pengodean. Pada bagian ini, kita membahas penggunaan lanjutan komentar SQL, termasuk menanamkan metadata, melakukan debugging kode SQL, dan menonaktifkan kode sementara. Teknik-teknik ini membantu merampingkan pengodean, sehingga lebih mudah mengelola dan menelusuri skrip SQL Anda secara efektif.

Menanamkan metadata

Anda dapat menggunakan komentar untuk menanamkan metadata tentang kode SQL, seperti nama penulis serta tanggal pembuatan atau modifikasi.

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

Debugging kode SQL

Anda dapat mengomentari bagian-bagian kode SQL untuk mengisolasi dan menguji bagian tertentu. Ini dapat membantu Anda menemukan di mana masalah mungkin terjadi.

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

Menonaktifkan kode sementara

Anda dapat menonaktifkan kode SQL sementara menggunakan komentar satu baris (--) atau komentar multibaris di SQL (/* ... */). Dengan cara ini, Anda dapat menyimpan kode di kueri tanpa mengeksekusinya, yang berguna untuk menguji bagian tertentu dari kode SQL Anda.

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

Mitos dan Kesalahpahaman

Terlepas dari penggunaannya yang luas, ada beberapa mitos dan kesalahpahaman yang masih bertahan tentang komentar SQL.

Penutup

Meskipun tampak sepele dalam pengembangan SQL, komentar dapat memperbaiki kode dan membuatnya lebih mudah dipahami. Dengan menulis komentar yang jelas dan terstruktur dengan baik, pengembang dapat memastikan kode SQL mereka tetap mudah diakses bahkan bertahun-tahun setelah pertama kali dibuat.

Jika Anda baru memulai perjalanan SQL, memahami dasar-dasarnya melalui kursus seperti SQL Fundamentals dapat membantu Anda memahami pentingnya komentar sejak awal. Seiring kemajuan, meraih SQL Associate Certification memvalidasi keterampilan Anda dan menunjukkan bahwa Anda dapat menulis kode yang jelas dan terdokumentasi dengan baik. Untuk semakin mengasah keterampilan, Intermediate SQL membahas lebih dalam kueri yang lebih kompleks, di mana komentar terperinci dapat digunakan untuk hal-hal seperti debugging.