SQL'de Yorumlar Nasıl Yazılır

Structured Query Language’ın kısaltması olan SQL, ilişkisel veritabanlarını yönetmek ve üzerinde işlem yapmak için güçlü bir dildir. SQL sorguları ilk bakışta kendini açıklıyor gibi görünse de, SQL ifadelerine yorum eklemek kodunuzun okunabilirliğini ve sürdürülebilirliğini artırabilir.

Bu eğitimde, kodunuzu daha basit ve okunur hale getirmek için SQL’de nasıl yorum ekleyeceğimizi göreceğiz.

Hızlı Yanıt: SQL'de Yorumlar Nasıl Yazılır

SQL sorgularınıza yorum eklemenin üç yolu vardır:

1. Tek Satırlık Yorumlar: Tek satırlık yorumlar -- çift tire ile başlar.

2. Aynı Satırdaki Yorumlar (Inline): Aynı satırdaki yorumlar, SQL ifadesinden sonra aynı satırda -- ile başlar.

3. Çok Satırlı (Blok) Yorumlar: Çok satırlı yorumlar /* ile başlar ve */ ile biter.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Altyapı:

SQL Yorumları Neden Önemlidir?

SQL yorumlarının önemli olmasının üç temel nedeni şunlardır:

• Kodun Amacını Netleştirme: Yorumlar kodun amacını ve mantığını açıklar; böylece siz ve başkaları kodu daha sonra incelediğinizde daha kolay anlayabilirsiniz.
• Takım Çalışmasını Güçlendirme: Yorumlar, diğer geliştiriciler için kodu belgelendirerek yaptıklarınızı kavramalarına yardımcı olur.
• Hata Ayıklama ve İyileştirmeye Yardımcı Olma: Yorumlar zaman içinde kodu hata ayıklama ve optimize etme sürecini kolaylaştırır; sorunları tespit etmeyi ve düzeltmeyi daha yönetilebilir hale getirir.

SQL Yorum Türleri

İhtiyaçlarınıza ve tercihlerinize bağlı olarak, SQL betiklerine yorum eklemenin üç yolu vardır.

Tek satırlık yorumlar

Yorumunuz tek bir satıra sığacaksa çift tire kullanın. Genellikle bağlam sağlamak için bu tür yorumları ilgili kod bloğunun üzerine yerleştirirsiniz.

--select the department name from the department table
SELECT dept_name
FROM employees.departments;Altyapı:

Aynı satırdaki yorumlar

Aşağıdaki örnekte gördüğümüz gibi, tek satırlık ve aynı satırdaki yorumlar SQL’de aynı söz dizimini kullanır ve özünde aynıdır; fark, konumlandırma ve kullanım biçimindedir. Aynı satırdaki yorumlar genellikle sorgunun belirli bir kısmını açıklamak için kullanılır.

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;
Altyapı:

Çok satırlı (blok) yorumlar

SQL’de birden fazla satıra yayılan daha uzun yorumlar eklemek için çok satırlı yorumları kullanabilirsiniz. Çok satırlı yorum eklemek için metninizi /* ile */ arasına alın. SQL yorumlayıcısı, /* ile */ arasına alınan metni yok sayar.

/*
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;
Altyapı:

SQL Yorumları Yazarken En İyi Uygulamalar

Yorumlarınızın kod tabanınız genelinde hem öz hem de bilgilendirici olmasını sağlamak için en iyi uygulamalara uymak önemlidir. Aşağıdaki bazı yönergeleri gözden geçirelim. 

Açıklık ve okunabilirlik

Yorumlarınızda aşırı karmaşık veya teknik terimler kullanmaktan kaçının. Bu sayede yorumlarınız açık ve öz olur; kod tabanına aşina olmayanlar bile anlayabilir.

İlgili bilgileri ekleyin

Verdiğiniz bilgilerin doğru ve açıkladığı koda doğrudan ilgili olduğundan emin olun. Karmaşık mantığın arkasındaki gerekçeyi açıklamalıdır. Şifreler ve API anahtarları gibi hassas bilgileri yorumlara dahil etmekten kaçının.

Düzenli güncelleyin

Güncelliğini yitirmiş yorumlar yanıltıcı olabilir ve teknik borca katkıda bulunur. Bu nedenle, kodu güncellerken yorumlarınızı da gözden geçirip en son değişiklikleri yansıtacak şekilde güncellemelisiniz.

Gereksiz tekrardan kaçının

Yorumlar yalnızca kodun ne yaptığını tekrar etmemelidir. Bunun yerine, yorumlar kodun "neden"ini – koddan hemen anlaşılmayan amacı veya bağlamı – açıklamalıdır.

SQL Yorumlarında Yaygın Hatalar

SQL kodunuza yorum eklemek, özellikle aylar sonra kodunuza geri dönmeniz gerektiğinde, her şeyin düzenli ve anlaşılır kalması için çok önemlidir. Ancak en iyi niyetlerle bile, yorumlarınızı yardımcı olmaktan çok kafa karıştırıcı hale getiren tuzaklara düşmek kolaydır. SQL yorumları yazarken kaçınmanız gereken bazı yaygın hatalar şunlardır:

Belirsiz veya yanıltıcı yorumlar

Okuyucuya değer katan, öz ve açık yorumlar yazın. Belirsiz veya hatalı yorumlar, hiç yorum olmamasından daha kötüdür.

Aşırı yorum yazma

Yorumlar faydalı olsa da, aşırı yorum yapmak kodun okunmasını ve bakımını zorlaştırabilir. Odağınızı kodun üst düzey amacını ve bariz olmayan yönlerini açıklamaya verin.

Kötü bir örneğe bakalım:

Bir SQL sorgusunda yorum. Görsel: Yazar.

Gördüğümüz gibi, değişkenlerimiz açık isimlere sahip olduğundan, yorumlar ek bir bağlam sağlamadan veya amacını açıklamadan kodu sadece tekrar etti.

Tutarsız yorumlama stili

Tutarsız stiller dikkat dağıtır ve kodun okunmasını zorlaştırır. Bunu önlemek için kod tabanınız genelinde tutarlı bir yorumlama stili kullanın. 

• Büyük/küçük harf kullanımı: Tutarlı bir büyük/küçük harf kullanımı kodunuzu okumayı ve anlamayı kolaylaştırır.
• Noktalama: Tüm yorumları noktayla bitirmek iyi bir uygulama olabilir, ancak katı bir kural değildir. Esas amaç tutarlılıktır.
• Biçimlendirme: Blok yorumlar ile aynı satırdaki yorumların kullanımına dair net kurallar belirleyerek tutarlılık sağlarsınız.

Bağlam eksikliği

Aşağıdaki örnekte SQL kodumuzun amacına dair üst düzey bir açıklama yer alıyor: "Raporlama için müşteri siparişlerini getir." Doğru olsa da, okuyucunun kodu tam olarak anlamasına yardımcı olacak bağlam eksik.

/*
* 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;
Altyapı:

Yorumumuzu geliştirmek için daha fazla ayrıntı ekleyebiliriz.

/* 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;
Altyapı:

SQL Yorumlarının Gelişmiş Kullanımları

Okunabilirliği artırmaya ek olarak, SQL yorumları kodlama sürecine de yardımcı olur. Bu bölümde, meta veri gömme, SQL kodunu hata ayıklama ve kodu geçici olarak devre dışı bırakma dahil olmak üzere SQL yorumlarının gelişmiş kullanımlarını inceliyoruz. Bu teknikler kodlamayı düzene sokar; SQL betiklerinizi etkili bir şekilde yönetmeyi ve sorun gidermeyi kolaylaştırır.

Meta veri gömme

SQL kodu hakkında yazar adı, oluşturma veya değiştirme tarihi gibi meta verileri yorumlara ekleyebilirsiniz.

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

SQL kodunu hata ayıklama

SQL kodunuzun bölümlerini yorum satırı yaparak belirli kısımları izole edip test edebilirsiniz. Bu, sorunun nerede oluştuğunu tespit etmenize yardımcı olabilir.

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;
Altyapı:

Kodu geçici olarak devre dışı bırakma

Tek satırlık yorumları (--) veya SQL'de çok satırlı yorumları (/* ... */) kullanarak SQL kodunu geçici olarak devre dışı bırakabilirsiniz. Böylece kodu sorguda tutup çalıştırmadan bırakabilirsiniz; bu da yalnızca belirli bölümleri test etmek istediğinizde faydalıdır.

SELECT column1, column2
FROM table1
WHERE condition1
/*
AND condition2
OR condition3
*/
Altyapı:

Efsaneler ve Yanılgılar

Yaygın kullanımına rağmen, SQL yorumları hakkında kalıcı bazı efsaneler ve yanılgılar vardır.

Son Düşünceler

SQL geliştirme açısından önemsiz gibi görünse de, yorumlar kodu iyileştirir ve anlaşılmasını kolaylaştırır. Açık ve iyi yapılandırılmış yorumlar yazarak geliştiriciler, SQL kodlarının ilk yazılışından yıllar sonra bile erişilebilir kalmasını sağlayabilir.

SQL öğrenme yolculuğunuza yeni başlıyorsanız, SQL Fundamentals gibi bir kursla temelleri kavramak, yorumlamanın önemini erken aşamada anlamanıza yardımcı olur. İlerledikçe, bir SQL Associate Certification almak becerilerinizi doğrular ve net, iyi belgelenmiş kod yazabildiğinizi gösterir. Yeteneklerinizi daha da geliştirmek için, Intermediate SQL daha karmaşık sorgulara derinlemesine iner; bu tür durumlarda ayrıntılı yorumlar, örneğin hata ayıklama gibi amaçlar için kullanılabilir.