Python Docstrings
Docstrings Nedir?
Programlamada, bir belge dizgisi, kodun belirli bir bölümünü belgelemek için bir yorum gibi kullanılan, kaynak kodda belirtilen bir dize değişmezidir. Python docstrings, bir fonksiyonun, metotun, sınıfın veya modülün tanımlanır. Docstring kuralları PEP 257'de açıklanmaktadır. Amacı kullanıcılara nesneye genel bir bakış sağlamaktır.
Docstrings üçlü-çift tırnak ( """) dizge biçimini kullanmalıdır. Bu, docstring'in çok satırlı olup olmadığına bakılmaksızın yapılmalıdır.
Örnek 1:
Üçlü tırnak işaretlerinin içinde, tanımından hemen sonra göründüğü şekliyle square() fonksiyonunun docstring’i bulunur.
Python Yorum Satırı (Comments) ve Docstrings Arasındaki Fark
Genel olarak yorum satırları, kodunuzu geliştiricilere açıklamaktır. Amaçlanan ana hedef kitle, Python kodunun geliştiricileridir. Yorumlar, programcıların programın amacını ve işlevselliğini daha iyi anlamasına yardımcı olan açıklamalardır. Python yorumlayıcısı tarafından tamamen göz ardı edilirler. Docstring, kullanıcılara kullanım ve işlevselliği açıklar. hedef kitlesi kullanıcılardır.
Yorum Satırları
Yorum satırları # sembolü kullanılarak oluştururlur.
PEP 8'e göre yorumların maksimum uzunluğu 72 karakter olmalıdır. Bu karakteri aşan yorumlar birden fazla satırda yazılmalı
Yorum satırı eklemenin faydaları,
Gözden Geçirme: Geliştirme aşamasında kullanılır. Gerçek kodlama uygulandıktan, incelendikten ve test edildikten sonra bu yorumları kaldırılmalıdır.
Kod Açıklaması: Açıklamalar, kodun belirli bölümlerinin amacını açıklamak için kullanılabilir.
Algoritmik Açıklama: Özellikle karmaşık algoritmalar kullanıldığında, algoritmanın nasıl çalıştığını veya kodunuzda nasıl uygulandığını açıklamak için kullanılabilir.
Etiketleme: Bilinen sorunların giderilmesi veya iyileştirme için belirtmek için kullanılır. Bazı örnekler şunlardır: BUG, FIXME ve TODO.
Docstring Kullanımı
Sınıf (Class) Docstring
Sınıf dokümanları aşağıdaki bilgileri içermelidir:
Amacı ve davranışının kısa bir özeti
Kısa bir açıklama ile birlikte herhangi bir genel metot
Herhangi bir sınıf özelliği
Sınıf kalıtım ile aktarılacaksa, alt sınıflar için arayüzle ilgili bilgiler
Sınıf yapıcı(constructor) parametreleri, __init__sınıf metotu docstring içinde belgelenmelidir .Bireysel metotlar, kendi dokümanları kullanılarak belgelenmelidir. Sınıf metot dokümanları aşağıdakileri içermelidir:
Metotun ne olduğu ve ne için kullanıldığı hakkında kısa bir açıklama
Argümanların tümü açıklanmalı
İsteğe bağlı olarak kabul edilen argümanlar ve ön tanımlı değeri belitmeliyiz
Metotu uygularken ortaya çıkan yan etkiler
Ortaya çıkan istisnalar/hatalar
Metotun ne zaman çağrılabileceğine dair herhangi bir kısıtlama
Paket ve Modül (Package and Module) Docstrings
Paket dokümanları, __init__.pydosyasının en üstüne yerleştirilmelidir . Bu belge dizesi, paket tarafından dışa aktarılan modülleri ve alt paketleri listelemelidir.
Modül dokümanları, sınıf dokümantasyonlarına benzer. Belgelenen sınıflar ve sınıf metotları yerine, artık modül ve içinde bulunan işlevlerdir. Modül dokümanları aşağıdakileri içermelidir:
Modülün ve amacının kısa bir açıklaması
Modül tarafından dışa aktarılan tüm sınıfların, istisnaların, işlevlerin ve diğer nesnelerin listesi
Bir modül işlevi için docstring, bir sınıf metoduyla aynı öğeleri içermelidir:
İşlevin ne olduğu ve ne için kullanıldığı hakkında kısa bir açıklama
Argümanların tümü açıklanmalı
İsteğe bağlı olarak kabul edilen tüm argümanlar belirtilmeli
İşlev yürütülürken ortaya çıkan herhangi bir yan etki
Ortaya çıkan istisnalar/hata
Fonksiyonun ne zaman çağrılabileceğine dair herhangi bir kısıtlama
Komut Dosyası (Script) Docstrings
Komut dosyalarının konsoldan çalıştırılan dosyalardır. Komut dosyaları için belge dizileri dosyanın en üstüne yerleştirilir ve kullanıcıların komut dosyasının nasıl kullanılacağına dair yeterli bir anlayışa sahip olmalıdır.
Docstring Formatları
- Google docstrings: Google’ın önerdiği belge biçimi
- reStructured Text: Resmi Python dokümantasyon standardı; Başlangıç dostu değil, zengin özelliklere sahip
- NumPy/SciPy Docstrings: reStructured ve Google Docstrings kombinasyonu
- Epytext Example: Epydoc’un bir Python uyarlaması; Java geliştiricileri için harika
