Ne Yaparlar ve Nasıl Kullanılır?
Python programlama dilinde, fonksiyon belgeleri (docstring), fonksiyonların ne yaptığını açıklayan ve nasıl kullanılması gerektiğini tanımlayan metinlerdir. Bu belgeler, kodunuzu anlaşılır hale getirmenin ve diğer geliştiricilere rehberlik etmenin önemli bir parçasıdır.
Fonksiyon Belgeleri (Docstring) Nedir?
Fonksiyon belgeleri veya docstring’ler, bir fonksiyonun hemen altında üçlü tek tırnak veya üçlü çift tırnak içine yazılan metinlerdir. Bu metinler, fonksiyonun ne yaptığını, nasıl kullanılması gerektiğini ve hangi parametreleri kabul ettiğini açıklar. Python topluluğu, iyi bir kod belgesi yazmanın önemini vurgular ve bu nedenle docstring kullanımı teşvik eder.
Fonksiyon Belgeleri Nasıl Oluşturulur?
Fonksiyon belgesi (docstring) oluşturmak için, bir fonksiyonu tanımladıktan sonra hemen aşağısına üçlü tek tırnak veya üçlü çift tırnak içinde belge metnini eklemeniz yeterlidir. İşte bir örnek:
def toplama(a, b):
"""
İki sayıyı toplar.
Parametreler:
a (float): Toplama işlemi için ilk sayı.
b (float): Toplama işlemi için ikinci sayı.
Dönüş Değeri:
float: İki sayının toplamı.
"""
sonuc = a + b
return sonuc
Yukarıdaki örnekte, toplama fonksiyonunun docstring’i üçlü tırnak içinde yer alır. Bu docstring, fonksiyonun ne yaptığını, hangi parametreleri aldığını ve dönüş değerini açıklar.
Fonksiyon Belgelerini (Docstring) Kullanma
Fonksiyon belgesi (docstring), aşağıdaki şekillerde kullanılabilir:
help() Fonksiyonu
Python’un help() fonksiyonunu kullanarak bir fonksiyonun docstring’ini görüntüleyebilirsiniz. İşte bir örnek:
help(toplama)
Bu komut, toplama fonksiyonunun docstring’ini görüntüler ve kullanıcıya fonksiyonun nasıl kullanılması gerektiği hakkında bilgi verir.
Otomatik Belge Üretme Araçları
Python için çeşitli belge üretme araçları vardır. Sphinx gibi araçlar, projeniz için otomatik olarak belge üretmenize olanak tanır. Bu araçlar, docstring’leri kullanarak projenizin ayrıntılı belgelerini oluşturabilir.
İyi Bir Docstring Nasıl Oluşturulur?
İyi bir docstring oluştururken aşağıdaki ipuçlarına dikkat edin:
- Fonksiyonun ne yaptığını ve nasıl kullanılacağını açıkça belirtin.
- Parametreleri, her bir parametrenin adını, türünü ve açıklamasını içeren bir şekilde belirtin.
- Dönüş değerini ve dönüş değeri türünü açıklayın.
- Örnekler veya kullanım senaryoları ekleyerek fonksiyonun nasıl kullanılacağını gösterin.
İşte daha ayrıntılı bir örnek:
def carpma(a, b):
"""
İki sayıyı çarpar.
Bu fonksiyon, verilen iki sayıyı çarparken kullanılır.
Parametreler:
a (float): Çarpma işlemi için ilk sayı.
b (float): Çarpma işlemi için ikinci sayı.
Dönüş Değeri:
float: İki sayının çarpımı.
Örnekler:
>>> carpma(5, 3)
15.0
>>> carpma(2.5, 4)
10.0
"""
sonuc = a * b
return sonuc
Özet
Python’da fonksiyon belgeleri (docstring), kodunuzu açıklamak, anlaşılır hale getirmek ve diğer geliştiricilere rehberlik etmek için kullanılır. Bir fonksiyonun docstring’ini oluşturmak için üçlü tek tırnak veya üçlü çift tırnak içine metni eklemeniz yeterlidir. help() fonksiyonu veya otomatik belge üretme araçlarıyla docstring’i görüntüleyebilirsiniz. İyi bir docstring, fonksiyonun ne yaptığını, nasıl kullanılacağını ve hangi parametreleri kabul ettiğini açıklar, böylece kodunuzu daha anlaşılır ve kullanışlı hale getirir.