koddla

Yazılımcıları bilgi ile güçlendirir.

Python docstring

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

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ı.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir

Back to top