Python Dilinde Açıklama Satırları (Comments) Kullanımı

Sözdizimi

# Bu tek satırlık bir yorumdur.
print("Merhaba, Dünya!")  # Bu da satır sonu yorumudur.

"""
Bu bir docstring'dir.
Genellikle fonksiyon, sınıf veya modül tanımlarında
açıklama yapmak için kullanılır.
"""
def topla(a, b):
    """
    İki sayıyı toplayan bir fonksiyon.
    Argümanlar:
        a (int): İlk sayı.
        b (int): İkinci sayı.
    Dönüş:
        int: İki sayının toplamı.
    """
    return a + b

Detaylı Açıklama

Tek Satırlık Yorumlar: Tek satırlık yorumlar, # karakteri ile başlar ve o satırın sonuna kadar devam eder. # karakterinden sonra yazılan her şey Python yorumlayıcısı tarafından yürütülmez. Bu tür yorumlar, belirli bir kod satırının ne yaptığını açıklamak, bir değişkenin amacını belirtmek veya geçici olarak bir kod parçasını devre dışı bırakmak için idealdir.

Çok Satırlık Yorumlar (Docstring'ler): Python'da resmi olarak çok satırlık bir yorum sözdizimi bulunmamaktadır. Ancak, üçlü tırnak işaretleri (tek veya çift tırnak olabilir) arasına alınan metinler, bir değişkene atanmadığı sürece Python yorumlayıcısı tarafından göz ardı edilir. Bu yapıya genellikle docstring adı verilir ve fonksiyonların, sınıfların, modüllerin veya metotların hemen altına yerleştirilerek onların işlevselliğini belgelemek için kullanılır. Docstring'ler, kodun otomatik belgelendirme araçları tarafından okunabilir olması nedeniyle tek satırlık yorumlardan farklı bir amaca hizmet eder.

Pratik Kullanım Örnekleri

**Örnek 1: Temel Tek Satırlık Yorum Kullanımı** Bu örnek, bir kod satırının amacını açıklamak için tek satırlık bir yorumun nasıl kullanıldığını gösterir.

# Kullanıcının adını saklayacak bir değişken tanımla
kullanici_adi = "softmush"
print(f"Hoş geldin, {kullanici_adi}!") # Kullanıcıya özel karşılama mesajı göster

**Örnek 2: Geçici Kod Devre Dışı Bırakma** Bir kod parçasını test amacıyla veya gelecekteki kullanım için geçici olarak devre dışı bırakmak için yorum satırları kullanılabilir.

def hesaplama_yap(x, y):
    sonuc = x * y
    # print(f"Ara sonuç: {sonuc}") # Bu satır şu anda devre dışı
    return sonuc + 10

print(hesaplama_yap(5, 3))

**Örnek 3: Docstring Kullanımı (Fonksiyon Belgelendirme)** Fonksiyonların ne iş yaptığını, aldığı argümanları ve döndürdüğü değeri açıklamak için docstring'ler yaygın olarak kullanılır.

def daire_alani_hesapla(yaricap):
    """
    Verilen yarıçap ile bir dairenin alanını hesaplar.

    Argümanlar:
        yaricap (float veya int): Dairenin yarıçapı.

    Dönüş:
        float: Hesaplanan daire alanı.
    """
    PI = 3.14159
    return PI * yaricap * yaricap

print(daire_alani_hesapla(5))

Önemli Notlar

• Aşırı Yorum Yapmaktan Kaçının: Açıkça anlaşılan veya kendi kendini açıklayan kod satırlarını yorumlamak gereksizdir. Yorumlar, kodun neden bu şekilde yazıldığına veya karmaşık mantığın açıklamasına odaklanmalıdır.

• Güncel Tutun: Kod değiştikçe yorumların da güncellenmesi esastır. Eski ve yanlış yorumlar, kodun anlaşılmasını zorlaştırabilir ve hatalara yol açabilir.

• Ne Yaptığını Değil, Neden Yaptığını Açıklayın: İyi yorumlar, kodun ne yaptığını (ki bu genellikle kodun kendisinden anlaşılır) değil, neden belirli bir yaklaşımın benimsendiğini veya belirli bir değeri ne amaçla kullandığınızı açıklar.

• Docstring Standartlarına Uyun: Özellikle projelerde çalışırken, PEP 257 gibi Python docstring standartlarına (örneğin Google, NumPy veya reStructuredText formatları) uymak, kodun belgelendirme sürecini kolaylaştırır ve tutarlılık sağlar.

• Geçici Devre Dışı Bırakma: Geliştirme aşamasında, test etmek veya sorun gidermek için kod satırlarını yorum satırı haline getirmek pratik bir yöntemdir. Ancak, temiz kodda kalıcı olarak yorumlanmış gereksiz kod bulundurmaktan kaçınılmalıdır.