Python'daki işlevleri yorumlamanın genel kabul gören bir yolu var mı? Aşağıdakiler kabul edilebilir mi?
#########################################################
# Create a new user
#########################################################
def add(self):
Yanıtlar:
Bunu yapmanın doğru yolu bir doktora sağlamaktır. Bu şekilde, help(add)yorumunuzu da tüküreceksiniz.
def add(self):
"""Create a new user.
Line 2 of comment...
And so on...
"""
Bu yorumu açmak için üç çift tırnak ve bitirmek için başka üç çift tırnak. Geçerli herhangi bir Python dizesini de kullanabilirsiniz. Çok satırlı olması gerekmez ve çift tırnaklar tek tırnaklarla değiştirilebilir.
Bakınız: PEP 257
Diğerleri zaten yazdığı gibi, bir doktora kullanın.
Bir adım daha ileri gidebilir ve doktorunuza bir doctest ekleyebilirsiniz , böylece işlevlerinizin otomatik olarak test edilmesini kolaylaştırabilirsiniz.
Bir docstring kullanın :
Bir modül, işlev, sınıf veya yöntem tanımında ilk deyim olarak gerçekleşen dize değişmezi. Böyle bir öğreti
__doc__, o nesnenin özel niteliği haline gelir .Tüm modüllerin normalde docstring'leri olmalı ve bir modül tarafından dışa aktarılan tüm fonksiyonlar ve sınıfların docstrings'i olmalıdır. Genel yöntemlerin (
__init__kurucu dahil ) ayrıca öğretileri de olmalıdır. Bir paket__init__.py, paket dizinindeki dosyanın modül öğretisinde belgelenebilir .Python kodunun başka bir yerinde meydana gelen dize değişmezleri de belge işlevi görebilir. Python bayt kodu derleyicisi tarafından tanınmazlar ve çalışma zamanı nesne öznitelikleri olarak (yani
__doc__atanmazlar) erişilemezler , ancak yazılım araçları tarafından iki tür ekstra docstring çıkarılabilir:
- Bir modül, sınıf veya
__init__yöntemin en üst düzeyinde basit bir atamadan hemen sonra meydana gelen dize değişmezleri "öznitelik docstrings" olarak adlandırılır.- Başka bir doktrinden hemen sonra meydana gelen dize değişmezleri "ek docstrings" olarak adlandırılır.
Özniteliğin ve ek öğretilerin ayrıntılı açıklaması için lütfen PEP 258 , "Doküman Tasarımı Spesifikasyonu" [2] 'na bakın ...
İyi yorumlama ilkeleri oldukça özneldir, ancak işte bazı yönergeler:
Python kodunuzda docstrings kullanma hakkında bilgi edinin .
Python doktora sözleşmelerine göre :
Bir işlev veya yöntemin öğretisi davranışını özetlemeli ve argümanlarını, dönüş değer (ler) ini, yan etkileri, ortaya çıkan istisnaları ve ne zaman çağrılabileceğine ilişkin kısıtlamaları belgelemelidir (varsa). İsteğe bağlı argümanlar belirtilmelidir. Anahtar kelime argümanlarının arayüzün bir parçası olup olmadığı belgelenmelidir.
Altın bir kural olmayacak, bunun yerine ekibinizdeki diğer geliştiricilere (eğer varsa) veya hatta altı ay yolda geri döndüğünüzde kendinize bir şey ifade eden yorumlar sağlayın.
Sadece bir "doktora kullan" demekten bir adım daha ileri giderdim. Pydoc veya epydoc gibi bir belge oluşturma aracı seçin (pyparsing'te epydoc kullanıyorum) ve bu araç tarafından tanınan biçimlendirme sözdizimini kullanın. Belgelerinizdeki delikleri tanımlamak için geliştirme sırasında bu aracı sık sık çalıştırın. Aslında, sınıfı uygulamadan önce sınıf üyeleri için öğretileri yazmaktan da faydalanabilirsiniz .
Öğretileri kullanın .
Bu, işlev açıklaması yorumları için PyCharm'da önerilen önerilen kongre :
def test_function(p1, p2, p3):
"""
my function does blah blah blah
:param p1:
:param p2:
:param p3:
:return:
"""def)? (Retorik bir soru değil.)
Bunun bir yorum olmaması gerektiğini, ancak çoğu (hepsi?) Cevapların önerdiği gibi bir doktora olduğunu kabul etsem de, numpydoc (bir doktora tarzı kılavuzu) eklemek istiyorum .
Bunu böyle yaparsanız, (1) otomatik olarak belge oluşturabilir ve (2) kişi bunu tanıyabilir ve kodunuzu okumak için daha kolay bir zamana sahip olabilirsiniz.
Bunu yapmak için üç tırnak kullanabilirsiniz.
Tek tırnak kullanabilirsiniz:
def myfunction(para1,para2):
'''
The stuff inside the function
'''Veya çift tırnak:
def myfunction(para1,para2):
"""
The stuff inside the function
"""