Python Kodunu Nasıl Belgelersiniz

Python’a yeni başladıysanız ve daha fazlasını öğrenmek istiyorsanız, DataCamp’in Orta Düzey Python kursunu alın.

Projenizi Belgelemenin Önemi

Belgelendirme, hangi programlama dilini kullandığınızdan bağımsız olarak üzerinde çalıştığınız her projenin temel bir parçasıdır. Çeşitli API’leri çalışır durumda olan ve birçok kullanıcı tarafından kullanılan bir uygulamaya sahip bir proje, eğer belgelendirme yoksa eksik kabul edilir. Bir an için kendinizi bir geliştirici olarak hayal edin: Belgesi olmayan bir projeyi kopyalamak veya projenin herhangi bir yönünü kullanmak isteseydiniz nasıl hissederdiniz? Eminim, mimarinize entegre etmekte zorlanırdınız.

Daha iyi bir belgelendirme projenizi daha başarılı kılar; çünkü projeyi ya da yazılımı dünyayla paylaştığınızda, özellikle açık kaynak olduğunda, insanların onu kullanmasını istersiniz ve hedefiniz daha da büyüktür. Ayrıca topluluğun projeye katkıda bulunmasını ve onu geliştirmesini de istersiniz.

Python programlama dilinin tanınmış yazarı, Kod, yazılandan daha sık okunur. diye alıntılanır. Bu söz, kodunuzun veya projenizin başkaları tarafından uygulanmasında belgelendirmenin önemini vurgular.

Kendinizi XYZ şirketinde çalışan biri olarak düşünün; ihbar sürenizi geçiriyorsunuz ve yöneticiniz projeyi bir iş arkadaşınıza devretmenizi istiyor. Ona bir KT (bilgi aktarımı) yapabilirsiniz, ancak ya iş arkadaşınız projedeki kodlardan birini başarıyla çalıştıramazsa? Kodun çalışmamasının birkaç nedeni olabilir; belki kodunuzun çalıştığı ikililer mevcut işletim sisteminin ikilileriyle eşleşmiyordur.

Belgelendirme Tam Olarak Nedir?

Belgelendirmenin birbiriyle bağlantılı birkaç bileşeni vardır. Bu bileşenler etrafında iyi yapılandırılmalı ve doğru bir belgelendirme sayılabilmesi için onlara uygun olmalıdır.

Özet düzeyde bileşenler şunlardır:

• Projenizin kod tabanının iyi yorumlandığından emin olmak.

• Python’un PEP-8 kodlama standartlarına uyması.

• Projenin nasıl inşa edildiğine dair somut öğreticiler; özellikle öğrenme odaklı amaçlarla geliştirilen açık kaynak projelerde.

• Gerekli paketlerin, yazılımı oluşturmak için kullanılan modüllerin nasıl kurulacağına ilişkin bir kılavuz; proje herhangi bir donanım içeriyorsa teknik özellik dökümü. Örneğin, anaconda, TensorFlow, Keras vb. nasıl kurulur.

• Yazılımın başarılı bir şekilde uygulanmasına yol açmış olabilecek her zaman adımındaki proje ilerlemelerine dair çeşitli tartışmalar.

• Geliştirme aşamasında kullanılan teknoloji yığınına ilişkin teknik bir açıklama sunan başvuru materyali.

• Projenin veya yazılım çözümünün mimari tasarımı.

Bu maddeler, iyi yapılandırılmış ve kusursuz görünen bir belgede bulunabilecek bileşenlerden sadece birkaçıdır. Tüm bu bileşenleri ayrı tutmak önemlidir; bu, ileride belgelendirmenin bakımını da kolaylaştırır.

Tartıştığımız bileşenlerin çoğunu içeren kapsamlı bir belgelendirme örneği, aşağıda gösterilene benzer olabilir:

Birçok kişi sık sık yorumlama ile belgelemeyi karıştırır ve benzer görür. Yorumlar, kodunuzu kullanıcıya, bakım yapan kişiye ve hatta gelecekteki referans olarak kendinize açıklamak için kullanılır. Yorumlar yalnızca kod düzeyinde çalışır ve belgelendirmenin bir alt kümesi olarak kategorize edilebilir. Yorumlar okuyucuya şunlarda rehberlik eder:

• kodunuzu anlamak,
• onu kendi kendini açıklayan hâle getirmek ve
• amacını ve tasarımını kavramak.

Python’un PEP-8 kodlama standartlarını takip ettiği için, yorumların da bu standartlara uyması gerektiğini unutmamak önemlidir. Resmî Python belgeleri, daha az yapısal kısıtlamaya sahip uzun metin bloklarında (docstring’ler veya yorumlar) satır uzunluğunun 72 karakterle sınırlanması gerektiğini belirtir.

Kodunuzun PEP-8 standartlarına uyup uymadığını kontrol etmek için Python’un pylint modülünü kullanabilirsiniz. Bu modül, yorumlar ve diğer tüm kod satırları için karakter sınırını değiştirmenize de olanak tanır.

Birkaç örneğe bakalım.

• Modül içe aktarma açıklaması

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Değişken tanımı açıklaması

n_classes = 10 # MNIST total classes (0-9 digits)

Yorumlamayı ve yapılması gerekenler/yapılmaması gerekenleri daha derinlemesine anlamak için şu faydalı yazıya göz atın.

Şimdi docstring’lerin proje kod tabanınızı belgelemede nasıl yardımcı olabileceğini öğrenelim.

Python Kodunu Belgelemek için Docstring’ler

Python Docstring, bir sınıf, modül, fonksiyon veya metod tanımında ilk ifade olarak yer alan, string literal biçimindeki belgelendirme dizgesidir. Docstring’lere herhangi bir Python nesnesinin (__doc__) özniteliğinden ve yerleşik help() işlevinden erişilebilir; bu da oldukça kullanışlıdır.

Ayrıca docstring’ler, kodun daha büyük bölümünün işlevselliğini, yani herhangi bir sınıfın, modülün veya fonksiyonun genel amacını anlamak için harikadır. Buna karşılık, yorumlar daha küçük olma eğiliminde olan kod, ifade ve deyimler için kullanılır. Bunlar, bir programcının esas olarak kendisi için yazdığı ve bir kod satırının veya ifadenin ne yaptığını bilmesini sağlayan, aynı zamanda o projeye katkıda bulunmak isteyen geliştirici için de açıklayıcı bir metindir. Kodunuzu belgelemenin, temiz kod ve iyi yazılmış programlar üretmenize yeterince hizmet edecek hayati bir parça olduğu açıktır. Her ne kadar belirtilmiş olsa da bunu yapmanın katı standartları ve kuralları yoktur.

Docstring yazmanın iki biçimi vardır: tek satırlık docstring’ler ve çok satırlı docstring’ler. Veri Bilimciler/programcılar projelerinde bu belgelendirme biçimlerini kullanırlar.

• Tek satırlık docstring’ler, tamamı tek satıra sığan docstring’lerdir. Üç tek tırnak veya üç çift tırnak kullanabilirsiniz; açılış ve kapanış tırnakları aynı olmalıdır. Tek satırlık docstring’lerde kapanış tırnağı açılış tırnağıyla aynı satırdadır. Yaygın gelenek, üçlü çift tırnak kullanmaktır.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Çok satırlı docstring’ler, tek satırlık docstring’lerdekiyle aynı string literal’leri içerir, ancak bunları açıklayıcı bir metnin öncelediği tek bir boş satır izler.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Yukarıdaki tablodan docstring biçimlerinden biri olarak Pydoc’u seçelim ve biraz inceleyelim.

Docstring’lere yerleşik Python __doc__ özniteliği ve help() işleviyle erişilebildiğini öğrendiniz. Ayrıca Pydoc adlı yerleşik modülü de kullanabilirsiniz; bu modül, sahip olduğu özellikler ve işlevsellikler açısından doc özniteliği ve help işlevinden oldukça farklıdır.

Pydoc, kodu iş arkadaşlarınızla paylaşmak veya açık kaynak hâline getirmek istediğinizde işe yarayacak bir araçtır; bu durumda çok daha geniş bir kitleyi hedefliyor olursunuz. Python belgelendirmenizden web sayfaları üretebilir ve bir web sunucusu başlatabilir.

Nasıl çalıştığına bakalım.

Pydoc modülünü çalıştırmanın en kolay ve uygun yolu, onu bir betik olarak çalıştırmaktır. Jupyter Lab hücresinde çalıştırmak için ünlem işaretini (!) kullanırsınız.

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Yukarıdaki çıktıya bakarsanız, Pydoc’un ilk kullanımının bir fonksiyon, modül, sınıf vb. için metin belgelendirmesi göstermek olduğunu görürsünüz; bunu help işlevinden daha iyi nasıl kullanabileceğinize bakalım.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Şimdi de glob belgelendirmesini help işlevini kullanarak çıkaralım.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Gördüğünüz gibi, glob tanımlı olmadığı için bir name error fırlatıyor. Dolayısıyla help işlevini kullanarak belgelendirmeyi almak için önce o modülü içe aktarmanız gerekir; Pydoc’ta ise böyle bir gereklilik yoktur.

Şimdi Pydoc modülünün en ilginç özelliğini, yani Pydoc’u bir web hizmeti olarak çalıştırmayı keşfedelim.

Bunu yapmak için Pydoc’u bir betik olarak, ancak -b argümanıyla çalıştırırsınız; bu, rastgele bir boş portta bir HTTP sunucusu başlatır ve belgelere etkileşimli olarak göz atmak için bir web tarayıcısı açar. Bu, özellikle sisteminizde çeşitli diğer hizmetler çalışırken ve hangi portun boşta olduğunu hatırlamadığınız durumlarda yararlıdır.

!python -m pydoc -b

^C

Yukarıdaki hücreyi çalıştırdığınız anda, rastgele bir port numarasıyla yeni bir pencere açılır ve web tarayıcısı aşağıda gösterilene benzer görünür.

Sinir ağı mimarisinin ağırlıklarını saklamak için kullanılan bir dosya biçimi olan h5py modülünün belgelendirmesine bakalım.

Python Projelerini Belgelendirirken Gerekli Unsurlar

Hedef, vizyon ve proje amacından bağımsız olarak, her projenin belgelendirmesi az çok aynıdır. Proje şu kategorilere girebilir:

• Özel (kişisel) Proje: Portföy oluşturmak için ya da serbest çalışırken bir GitHub deposu yönetmek için olabilir.

• Birlikte Çalışılan (ekip) Projeler: Kurumunuzda yürütülen bir proje ya da bir Kaggle yarışması üzerinde çalışmak olabilir.

• Açık Kaynak Projeler: Açık kaynak projeler, esas olarak geniş bir kitleyle paylaşılmaya odaklanır. Uzun vadede iş birliği, katkı ve kod tabanının ve belgelerin sürdürülebilirliğini bekler.

Yukarıdaki üç proje kategorisinin vizyonları farklı olsa da, belgelendirme şablonu tüm proje türleri arasında paylaşılabilir.

Diyelim ki bir açık kaynak proje üzerinde çalışıyorsunuz ve bunun için düzenli olarak güncellenen ayrıntılı bir belgelendirme içeren bir GitHub deposu oluşturmanız gerekiyor; aklınızda tutmanız gereken temel noktalar şunlardır:

• Gereksinimler dosyası: Çoğu zaman yazarlar bunu unutma eğilimindedir, ancak gereksinimler dosyası çok önemlidir. Kullanıcıların kodunuzu hızla çoğaltmasına yardımcı olur. Genellikle projede kullanılan tüm paketleri, modülleri ve bunların sürümlerini içeren bir metin dosyasıdır. Gereksinimler Readme dosyasında da belirtilebilir, ancak ayrı olması her zaman daha iyidir; çünkü kullanıcı bu dosyayı bir pip komutuyla çalıştırabilir ve tüm bağımlılıklar kendi sistemlerine kurulmuş olur.

• Readme: Readme dosyası genellikle bir markdown formatıdır ve birçok projenin bel kemiği işlevi görür. Projenin özeti, özellikleri ve amacı güzel bir logoyla birlikte. Projenin kurulumu veya çalıştırılması için talimatları içermelidir. Ek olarak, önceki sürümden bu yana önemli değişiklikleri ekleyin. Readme içinde test betikleri veya kodu başarıyla çalıştırmaya yönelik hızlı bir tur, kullanıcıya projenizi sürdürme konusunda daha fazla güven verir. Ayrıca kullanıcıların karşılaşabileceği olası sorunları da vurgulayabilir.

• Nasıl İş Birliği Yapılır: Özellikle açık kaynak projelerde çalışırken önemlidir. Yeni katılımcıların projeye nasıl katkı sağlayabileceğini içermelidir. Buna yeni özellikler geliştirmek, bilinen hataları düzeltmek, belgelendirme eklemek, yeni testler eklemek veya sorun bildirmek dâhildir. Katılımcılar aynı projenin v2.0 sürümünü bile yayımlayabilir ve projeyi daha ileriye taşıyabilirler.

• Lisans: Projenizin kullandığı lisansı açıklayan düz metin bir dosya. Özellikle açık kaynak projeler için Boost, Apache, MIT vb. lisanslar kritik önemdedir. Bu, projenin ticari olarak ücretsiz kullanılıp kullanılamayacağını veya hangi ölçüde kullanılabileceğini kullanıcıya bildirir.

• Görev ataması: Kaggle gibi paylaşılan bir projede çalışıyorsanız, her üyeye atanan görevleri ve görevin ilerleme düzeyini tanımlayabilirsiniz. Bu, projede kaydedilen genel ilerlemenin izlenmesine yardımcı olur.

• Çerçeve Yeniden Kullanılabilirliği: Kaggle gibi paylaşılan projelerde hayati bir rol oynar; ekip arkadaşlarınız sizin geliştirmiş olabileceğiniz bileşenleri yeniden kullanabilir ve bu çok zaman kazandırabilir. Örneğin, veri ön işleme hattı, veri çapraz doğrulama betiği vb.

Son derece tavsiye edilen, çok iyi yapılandırılmış ve bir açık kaynak projenin nasıl görünmesi gerektiğine mükemmel bir örnek olabilecek bir belgelendirme için huggingface transformers GitHub deposuna göz atın.

Sonuç

Öğreticiyi tamamladığınız için tebrikler.

Sizler için iyi bir alıştırma, Pydoc modülünü ve Epydoc ile Google docstring’leri gibi diğer Python docstring biçimlerini biraz daha keşfetmek ve birbirlerinden nasıl farklı olduklarını bulmak olacaktır.

Lütfen bu öğreticiyle ilgili tüm sorularınızı aşağıdaki yorumlar bölümünde sormaktan çekinmeyin.

Kaynaklar:

• Python’da Docstring’ler

Python’a yeni başladıysanız ve daha fazlasını öğrenmek istiyorsanız, DataCamp’in Orta Düzey Python kursunu alın.