İyi kod, anlaşılmasına yardımcı olacak yorumları içerir ve dokümanlar bu konuda önemli bir rol oynayabilir.

Uygun belgeler olmadan kodunuzu anlamak, sürdürmek ve hata ayıklamak zor olabilir. Python'da, kodun nasıl çalıştığına dair kısa açıklamalar ve örnekler sağlamak için belge dizilerini kullanabilirsiniz.

Belge Dizileri Nedir?

Belge dizileri, Python kodunuza ekleyebileceğiniz, ne yaptığını ve nasıl kullanılacağını açıklayan dizelerdir. Kod parçası bir olabilir Python işlevi, bir modül veya bir sınıf.

Belge dizileri, standart Python yorumlarına çok benzer, ancak bazı farklılıkları vardır. Python yorumları, geliştiricilere kodun iç işleyişi hakkında uygulama ayrıntıları veya kodu genişletirken akılda tutulması gereken uyarılar gibi ek bilgiler sağlar.

Öte yandan, belgeler çoğunlukla, uygulama ayrıntılarını bilmesi gerekmeyen ancak ne yaptığını ve nasıl kullanılacağını anlaması gereken kod kullanıcılarına bilgi sağlar.

Belge Dizileri Nasıl Yazılır?

Docstring'leri genellikle belgelemek istediğiniz kod bloğunun başına eklersiniz. Bunları üçlü tırnak içine almalısınız (). Tek satırlık doküman dizileri veya çok satırlı doküman dizileri yazabilirsiniz.

instagram viewer

Tek satırlık belgeler, çok fazla belge gerektirmeyen basit kodlar için uygundur.

Aşağıda çarpma adı verilen bir fonksiyon örneği verilmiştir. Docstring, çarpma işlevinin iki sayıyı aldığını, onları çarptığını ve sonucu döndürdüğünü açıklar.

kesinlikleçarpmak(bir, b):
İki sayıyı çarpar ve sonucu verir
geri dönmek bir * b

Ayrıntılı belgeler gerektiren daha karmaşık kodlar için çok satırlı belgeler kullanın.

Aşağıdaki Araba sınıfını göz önünde bulundurun:

sınıfAraba:

 A sınıftemsil edenAarabanesne.
 Öznitellikler:
 kilometre (float): Arabanın mevcut kilometresi.


 Yöntemler:
 sürüş (mil): Arabayı sürer için belirtilen mil sayısı.


kesinlikle__içinde__(öz, kilometre):
 self.mileage = kilometre


kesinliklesürmek(kendisi, mil):

 Arabayı sürer için belirtilen mil sayısı.


 argümanlar:
 mil (float): Sürülecek mil sayısı.
 İadeler:
Hiçbiri

 self.mileage += mil

Yukarıdaki sınıfa ilişkin belgeler, sınıfın neyi temsil ettiğini, niteliklerini ve yöntemlerini açıklar. Bu arada, drive yöntemine ilişkin belgeler, yöntemin ne yaptığı, beklediği bağımsız değişkenler ve ne döndürdüğü hakkında bilgi sağlar.

Bu, bu sınıfla çalışan herkesin onu nasıl kullanacağını anlamasını kolaylaştırır. Belge dizilerini kullanmanın diğer faydaları şunları içerir:

  • Kod sürdürülebilirliği: Docstrings, kodun nasıl çalıştığına dair net bir açıklama sağlayarak, geliştiricilerin hataya yol açmadan kodu değiştirmesine ve güncellemesine yardımcı olur.
  • Daha kolay işbirliği: Birkaç geliştirici aynı kod tabanında işbirliği yaptığında, örneğin, Visual Studio canlı paylaşım aracı—docstrings, geliştiricilerin kodu ekipteki herkesin anlayabilmesi için tutarlı bir şekilde belgelemesine olanak tanır.
  • Geliştirilmiş kod okunabilirliği: Docstrings, hangi kodun yaptığına dair üst düzey bir özet sağlar ve bu da izin verir tüm kodu incelemeden amacını hızlı bir şekilde anlamak için kodu okuyan herkes engellemek.

Doküman Dizgesi Formatları

İyi bir doküman dizisi, bir kod parçasının ne yaptığını, beklediği bağımsız değişkenleri ve gerekirse uygulama ayrıntılarını açıklamalıdır. Özellikle, kodu kullanan herkesin bilmesi gereken uç durumları içermelidir.

Temel bir docstring formatı aşağıdaki bölümleri içerir:

  • Özet satırı: Kodun ne yaptığına dair tek satırlık bir özet.
  • Argümanlar: Veri tipleri de dahil olmak üzere işlevin beklediği argümanlar hakkında bilgi.
  • Dönüş değeri: Veri türü de dahil olmak üzere işlevin dönüş değeri hakkında bilgi.
  • Yükseltmeler (isteğe bağlı): İşlevin artırabileceği istisnalar hakkında bilgi.

Belge dizilerinizi temel almak için seçebileceğiniz başka biçimler olduğu için bu yalnızca temel bir biçimdir. En popüler olanlar Epytext, reStructuredText (reST olarak da bilinir), NumPy ve Google docstrings'dir. Aşağıdaki örneklerde gösterildiği gibi, bu biçimlerin her birinin kendi sözdizimi vardır:

Epytext

Epytext biçimini izleyen bir doküman dizisi:

kesinlikleçarpmak(bir, b):

 İki sayıyı birlikte çarpın.
 @param a: Çarpılacak ilk sayı.
 @type a: int
 @param b: Çarpılacak ikinci sayı.
 @tip b: int
 @return: İki sayının çarpımı.
 @rtype: int

geri dönmek bir * b

yeniden Yapılandırılmış Metin (reST)

reST biçimini izleyen bir doküman dizisi:

kesinlikleçarpmak(bir, b):

 İki sayıyı birlikte çarpın.
 :param a: Çarpılacak ilk sayı.
 :a yazın: int
 :param b: Çarpılacak ikinci sayı.
 :tip b: int
 :geri dönmek: İki sayının çarpımı.
 :rtip: int

geri dönmek bir * b

Dizi

NumPy biçimini izleyen bir doküman dizisi:

kesinlikleçarpmak(bir, b):

 İki sayıyı birlikte çarpın.
 parametreler

 bir: int
 Çarpılacak ilk sayı.
 b: int
 Çarpılacak ikinci sayı.
 İadeler

 int
 İki sayının ürünü.

geri dönmek bir * b

Google

Google biçimini izleyen bir doküman dizisi:

kesinlikleçarpmak(bir, b):

 İki sayıyı birlikte çarpın.
 argümanlar:
 a (int): Çarpılacak ilk sayı.
 b (int): Çarpılacak ikinci sayı.
 İadeler:
 int: İki sayının çarpımı.

geri dönmek bir * b

Dört docstring biçiminin tümü, çarpma işlevi için yararlı belgeler sağlasa da, NumPy ve Google biçimlerinin okunması, Epytext ve reST biçimlerine göre daha kolaydır.

Docstrings'e Testler Nasıl Dahil Edilir?

Doctest modülünü kullanarak doküman dizilerinize test örnekleri ekleyebilirsiniz. doctest modülü, etkileşimli Python oturumları gibi görünen metinler için docstring'i arar ve ardından gerektiği gibi çalıştıklarını doğrulamak için bunları yürütür.

Belge testlerini kullanmak için, belge dizisine örnek girdileri ve beklenen çıktıları ekleyin. Aşağıda bunu nasıl yapacağınıza dair bir örnek verilmiştir:

kesinlikleçarpmak(bir, b):

 İki sayıyı birlikte çarpın.
 parametreler

 bir: int
 Çarpılacak ilk sayı.
 b: int
 Çarpılacak ikinci sayı.


 İadeler

 int
 İki sayının ürünü.
 örnekler

 >>> çarp(2, 3)
6
 >>> çarp(0, 10)
0
 >>> çarp(-1, 5)
-5

geri dönmek bir * b

bu örnekler bölüm, farklı bağımsız değişkenlere sahip üç işlev çağrısı içerir ve her biri için beklenen çıktıyı belirtir. Doctest modülünü aşağıda gösterildiği gibi çalıştırdığınızda, örnekleri çalıştıracak ve gerçek çıktıyı beklenen çıktıyla karşılaştıracaktır.

piton -m doctest çarpma.py

Herhangi bir farklılık varsa, doctest modülü bunları başarısızlık olarak bildirir. Doctest'leri bunun gibi docstrings ile kullanmak, kodun beklendiği gibi çalıştığını doğrulamanıza yardımcı olur. Doktora testlerinin daha kapsamlı testlerin yerine geçmediğini unutmayın. Python kodunuz için birim testleri ve entegrasyon testleri.

Doküman Dizilerinden Dokümantasyon Nasıl Oluşturulur

Python kodunuzu belgelemek için belge dizilerini kullanmanın temellerini ve yüksek kaliteli belgelerin önemini öğrendiniz. Bir adım öteye götürmek için, modülleriniz ve işlevleriniz için ilgili belge dizilerinden belgeler oluşturmak isteyebilirsiniz.

Kullanabileceğiniz en popüler belge oluşturuculardan biri Sphinx'tir. Varsayılan olarak reST docstring biçimini destekler, ancak bunu Google veya NumPy biçimiyle çalışacak şekilde yapılandırabilirsiniz.