Programlama dillerinde docstring kaynak kodu içerisinde tanımlanmış bir metni ifade eder. Docstring’leri yorum olarak düşünülebiliriz. Bir class, modül veya fonksiyonun işlevini tanımlamak için kullanırız. Alışılagelmiş kaynak kodu yorumlarının aksine, docstringler programımızı çalıştırdığımızda veya derlediğimizde kaynak kodundan silinmezler. Bu şekilde kodumuzu herhangi bir zamanda inceleme fırsatı buluruz. Aynı zamanda, bir yardım aracı ile veya metadata olarak da docstring içeriğini gösterebiliriz.
Python docstring kullanımını destekler.
Docstring’i nasıl kullanmalıyız?
Muhtemelen Python kılavuzundaki PEP 8 ve PEP 257‘yi okumuşsunuzdur. Hatta bir çok programınızda docstring de kullanmışsınızdır. Ancak bir modül veya class tanımındaki docstring içerisine ne yazmanız gerektiği konusunda hala şüphe duyuyor olabilirsiniz.
Kısaca söylemek gerekirse, örneğin bir modül için, o modüldeki fonksiyonların veya class tanımlarının ne işe yaradığını belirten bir açıklama yazarız. Buna biraz daha detaylı bakalım. Öncelikle Python kılavuzu biz şunu diyor:
Bir script (herhangi bir program) içerisindeki docstring o scriptin, help(script) komutu ile bastırılabilir “kullanımını” gösteren bir mesaj içerir. Bu şekilde hazırlanan docstring, script fonksiyonlarının ve komut satırındaki kullanım söz öbeğinin, ortam değişkenlerinin ve dosyalarının açıklamasını sunar. Kullanım kılavuzu kapsamlı olabilir. Ya da yeni bir kullanıcı için scripti basit bir şekilde kullanmaya yeterli olacak kadar olabilir. Daha bilgili kullanıcılar için tüm opsiyon ve argümanları listeleyecek hızlı bir referans da içerebilir.
Modül için genellikle modüldeki class, exception ve fonksiyonları (ve diğer nesneleri) birer satırda özetler. (Bu özet genellikle nesnenin docstring’inden daha kısa tutulur.) Bir paket için docstring ayrıca alt paketleri ve modülleri de listeler.
Bir class için bu class’ın davranışını ve public metot ve değişkenlerini özetler. Eğer bu sınıf başka sınıflar tarafından alt sınıf haline getirilecekse, ve başka alt sınıflar için arayüze sahipse, bunlar ayrı ayrı belirtilir.
Bir fonksiyon veya metot için kısaca fonksiyonun veya metodun çalıştırılınca göstereceği etkiyi özetleriz. Bu kullanımı; “Bunu yap”, “şunu döndür” şeklinde düşünebiliriz. Bu tarz bir özetin uzun bir açıklama olarak yazılmaması önerilir. Çok satırda-docstring kulandığımızda fonksiyonun argümanları, döndürdüğü değerler, yan etkiler, hatalar veya kısıtlamaları yazarız. İsteğe bağlı argümanları ayrıca belirtiriz.
Docstring örneği
Şöyle düşünelim; Bir kullanıcı yazdığımız bir modülü help(modulum) ile kullansın. Bu kullanıcı ne öğrenmek ister? Örneğin;
"""Bu modül şunu şunu yapar."""
class Blah(object):
"""Bu class şunu şunu yapar."""
çalıştıralım:
>>> import x; help(x)
Çıktı:
Help on module x:
NAME
x - Bu modül şunu şunu yapar.
FILE
/tmp/x.py
CLASSES
__builtin__.object
Blah
class Blah(__builtin__.object)
| Bu class şunu şunu yapar.
|
| Veri ve diğer özellikler aşağıda tanımlanır:
|
| __dict__ = <dictproxy object>
| nesneler için bir dictionary
|
| __weakref__ = <attribute '__weakref__' of 'Blah' objects>
| zayıf referanslar için bir nesne
Gördüğünüz gibi bu sınıfa ait bilgileri ayrıntılı bir şekilde bastırdık. Bu şekilde her öğenin hangi işe yaradığını kapsamlı bir şekilde belirtebiliriz.
Docstring Formatları
Python docstring’lerini birden fazla formatta yazabiliriz. Genellikle kullanılan formatlara bakalım:
– Epytext
Tarihsel olarak baktığımızda javadoc tarzı bir stil genellikle tercih edilir. Bu sebeple Epydoc formatını buna dayandırır. Örnek:
"""
Bu bir javadoc stili.
@param param1: ilk parametre
@param param2: ikinci parametre
@return: döndürülen öğe için açıklama
@raise keyError: hata oluşturur
"""
– reST
Günümüzde ise çoğunlukla reStructuredText (reST) formatını kullanırız. Bu format ayrıca Sphinx‘in kullandığı formattır.
Örnek:
"""
reST stili
:param param1: ilk parametre
:param param2: ikinci parametre
:returns: döndürülen öğe için açıklama
:raises keyError: hata oluşturur
"""
Google kendi formatını kullanır.
"""
Google stili
Args:
param1: ilk parametre
param2: ikinci parametre
Returns:
döndürülen öğe için açıklama
Raises:
KeyError: hata oluşturur
"""
– Numpydoc
Numpy kendi formatının kullanılmasını tavsiye eder. Bu format Google formatına baz alır.
"""
numpydoc stili
.
Parameters
----------
first : array_like
`first` adındaki ilk parametre için açıklama
second :
ikinci parametre
third : {'value', 'other'}, optional
üçüncü parametre, default:'value'
Returns
-------
string
döndürülen metin
Raises
------
KeyError
key hatası
OtherError
diğer hatalar
"""
Docstring formatı dönüştürme/oluşturma
Pyment tarzı bir script ile otomatik olarak açıklamalar oluşturabiliriz. Ya da bir formattan diğer formata dönüştürebiliriz.
Not: Örnekler Pyment dökümanlarından alındı.