Fonksiyon/sınıf/modül belgeler, yani kodu kendisi yorum. en iyi uygulamaları arıyorum İdeal insan okunabilir ve Python belgelerine programları tarafından sarf hem yorum şablon istiyorum.

Python documentation on docstrings okudum.

Bu kısmını anladım:

İlk satırı her zaman nesnenin amacının kısa ve öz bir özet olmalıdır. Kısalık için, bu başka bir anlamı varsa adını bir fiil bir işlev çalışmasını açıklayan olursa hariç) tarafından kullanılabilir olduğu açıkça nesnenin adı ya da olmamalı. Bu satırı büyük harfle başlar ve nokta ile bitmelidir.

Eğer belgeleme karakter dizisinde birden fazla satır var ise ikinci satır boş, görsel olarak açıklamasını geri kalanından ayıran Özet olmalıdır.

Bu cümleyi biraz daha açıklama ihtiyacı:

Aşağıdaki satırları bir veya daha fazla paragraf nesne arıyor şekilleri, yan etkileri, vb tarif edilmelidir.

Özellikle, iyi yorumladı fonksiyonları ve sınıfları örnekleri arıyorum.

9 ** Sphinx markup constructs kontrol etmelisiniz. Bütün havalı çocuklar yapıyor.

11**. yani

İşlev veya yöntemin öngörüyor bir komut olarak etkisi ("bunu Yap", "O") döndürür.

Gereksiz yere kendini tekrar ya da fazlasıyla açık anlatan kaçınmalısınız. Ne olmayan örnek:

def do_things(verbose=False):
    """Do some things.
    :param verbose: Be verbose (give additional messages).
    """
    raise NotImplementedError

Eğer bir şey olmayan açık tarif etmek istersen farklı bir hikaye olurdu; örneğin, ayrıntılı iletiler stdout logging dere kenarında oluşmasına neden olur. Bu özel Python için değil, ama daha fazla bir şekilde el-dalgalı self-documenting code code/documentation DRY gibi idealleri.

Mümkünse belirli türleri (veya arayüzü gibi soyut türleri genellikle misin) söz önlemek için deneyin. Sözprotokollergenellikle ördek yazarak bir bakış açısından daha yararlı olduğunu (yani "" set ya da "değişken sipariş sırası" 5**) yerine. yerine iterable Çok edebi bir kod gördüm ve ağır WRT :rtype: ve ördek ile kavgalı zihniyeti de yazmak için bulduğum :type param: işlev düzeyi Dokümantasyon,.