🙎 👶🏽 👨‍👩‍👦 PEP 257 dalam bahasa Rusia. (Perjanjian Docstrings) 🈲 🧣 💑

Halo Habr. Ada saat-saat ketika Anda ingin membenamkan diri dalam bahasa sebanyak mungkin dan memahami semua seluk-beluknya. Dalam kasus Python, salah satu cara terbaik untuk melakukan ini adalah membaca dokumentasi dan PEP di situs web resmi. Saya tidak melakukan ini pada saat itu, karena saya tidak dapat memahami banyak aspek “teknis”, dan tidak ada varian terjemahan Rusia. Sekarang saya memutuskan untuk menerjemahkan PEP-257 sendiri, yang menceritakan tentang dokumentasi kode yang benar, karena pasti ini akan membantu pemula lebih memahami pendekatan "Python" yang sebenarnya dalam menulis kode. Saya menerjemahkan contoh kode ke dalam bahasa Rusia, tetapi hanya untuk menyampaikan makna dengan lebih baik. Dalam pemrograman nyata, cobalah menulis baris dokumentasi dalam bahasa Inggris. Saya juga langsung mengatakan bahwa sebagai sinonim untuk istilah "docstring" saya menggunakan kata-kata: "dokumentasi" dan "garis dokumentasi". Baiklah, mari kita beralih ke terjemahan itu sendiri.

Semangat	257
Judul:	Perjanjian dokumen
Penulis:	David Goodger <goodger di python.org>, Guido van Rossum <guido at python.org>
Diskusi:	doc-sig di python.org
Status:	Aktif
Sebuah tipe:	Informasi
Dibuat:	29 Mei 2001
Publikasi:	13-Juni-2001

anotasi

PEP ini mendokumentasikan semantik dan konvensi yang terkait dengan penggunaan dokumen Python.

Pembenaran

Tujuan PEP ini adalah untuk menstandarkan struktur tingkat tinggi dari baris dokumen: untuk menggambarkan apa yang seharusnya berisi dan menjelaskannya (Kami tidak akan membahas sintaks markup aktual). PEP tidak mengandung pedoman ketat, tetapi rekomendasi:

“Konvensi konvensional memberikan kejelasan, konsistensi, kemudahan pemeliharaan dan menumbuhkan kebiasaan pemrograman yang baik. Tetapi mereka tidak memaksa Anda untuk bertindak melawan kehendak Anda. Ini Python! "

Tim Peters di comp.lang.python, 2001-06-16

Jika Anda menghindari perjanjian yang diterima secara umum, Anda akan menyipit di terburuk. Tetapi ada beberapa aplikasi (misalnya, sistem dokumentasi seperti Docutils) yang akan memungkinkan Anda untuk mencapai hasil yang lebih baik jika Anda tahu tentang perjanjian dan mengikuti mereka.

Spesifikasi

Apa itu Docstring?

String dokumentasi adalah string literal yang merupakan pernyataan pertama dalam modul, fungsi, kelas, atau definisi metode. String semacam itu menjadi tersedia ketika menangani atribut __doc__ khusus dari objek ini.

Semua perpustakaan, serta fungsi dan kelas yang diekspor oleh mereka, harus memiliki dokumentasi. Metode publik (termasuk konstruktor __ init__) juga harus memiliki dokumentasi. Paket itu sendiri dapat didokumentasikan di dalam file __init__.py yang terletak di direktori yang sesuai.

Literal string yang ditemukan di tempat lain dalam kode juga dapat memainkan peran dokumentasi. Mereka tidak dikenali oleh kompiler kode byte Python dan tidak tersedia sebagai atribut objek selama eksekusi program (mis. Mereka kekurangan informasi dalam __ doc__). Tetapi ada dua jenis tambahan garis dokumentasi yang diambil menggunakan alat perangkat lunak lain:

Literal string yang muncul segera setelah penugasan sederhana pada modul, kelas atau level __init__ disebut “string dokumentasi atribut”. (atribut atribut)
Literal string yang muncul segera setelah baris dokumentasi lain disebut "baris dokumentasi tambahan." (dokumen tambahan)

Silakan lihat PEP 258, "Spesifikasi Proyek Docutils," untuk rincian lebih lanjut tentang atribut dan dokumen tambahan.

[sekitar ed. Penjelasan PEP 258]

def f(x):
    """  docstring   __doc__ ."""
    """
     "additional docstrings",   , 
        Docutils.
    """
    return x**2

f.a = 1
""" "attribute docstrings"   : f.a"""

Untuk konsistensi, selalu gunakan "" "triple double quotes" "" di sekitar baris dokumentasi. Jika Anda menggunakan karakter garis miring terbalik ("\"), maka gunakan "" "string rangkap dua kutip mentah" "dalam dokumentasi Anda. Untuk docstring yang mengandung karakter Unicode, gunakan u "" "string Unicode dalam tanda kutip ganda" "". [sekitar string unicode telah kehilangan artinya dalam python 3.x]

Ada dua bentuk docstring: single-line dan multi-line.

Baris dokumentasi baris tunggal

String single-line digunakan untuk kasus yang jelas dan mereka harus benar-benar berada pada baris yang sama. Contohnya:

def kos_root():
    """    root KOS"""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Catatan:

. .
, . docstring .
, .
— «», . (« », « »), . , : « ...».

« » «Return pathname» «Returns pathname». PEP-257 , .

«», / ( ). :

def function(a, b):
    """function(a, b) -> list"""

, C ( ), . . - :

def function(a, b):
    def function(a, b):
    """ X   ."""

( -, « X» !)

, : « », «description» . , , .

Dokumentasi multi-baris terdiri dari baris ringkasan yang memiliki struktur yang sama dengan dokumen baris tunggal, diikuti oleh baris kosong, dan kemudian deskripsi yang lebih kompleks. "Baris ringkasan" dapat digunakan melalui dokumentasi otomatis; oleh karena itu, sangat penting untuk menempatkannya pada satu baris dan kemudian membuat operan dalam satu baris. Baris ringkasan ditulis segera setelah tanda kutip pembukaan, tetapi diizinkan untuk melakukan tanda hubung dan mulai dari baris berikutnya. [sekitar setelah kalimat ini, saya senang, karena ada orang yang terus-menerus mencoba membuktikan kepada saya bahwa tidak mungkin untuk melakukan transfer dalam hal apa pun :-)] Pada saat yang sama, seluruh dokumen harus memiliki lekukan yang sama dengan tanda kutip pembuka pada baris pertama (lihat contoh di bawah).

Biarkan baris kosong setelah semua dokumentasi (baris tunggal atau multi-baris) yang digunakan di kelas; secara umum, metode kelas harus dipisahkan satu sama lain oleh satu baris kosong, oleh karena itu baris dokumentasi kelas juga harus dipisahkan dengan cara ini dari metode pertama.

Dokumentasi skrip (program yang berdiri sendiri) adalah pesan "tentang penggunaan yang tepat" dan mungkin akan dicetak ketika skrip dipanggil dengan argumen yang tidak valid atau tidak ada (atau dengan opsi "-h" untuk mendapatkan "bantuan"). Baris dokumentasi seperti itu harus menggambarkan fungsionalitas dan sintaks parameter skrip, serta variabel lingkungan dan file yang digunakan. Pesan ini mungkin agak rumit (manualnya panjangnya beberapa layar penuh), tetapi pada saat yang sama harusnya nyaman bagi pengguna baru sehingga mereka dapat menggunakan perintah dengan benar. Juga, manual harus memberikan deskripsi yang jelas tentang semua parameter dan argumen untuk pengguna yang lebih berpengalaman.

Dokumentasi modul biasanya harus berisi daftar kelas, pengecualian dan fungsi (dan objek penting lainnya) yang diekspor menggunakan perpustakaan, serta penjelasan satu baris untuk masing-masing kelas. (Ringkasan ini, sebagai suatu peraturan, memberikan lebih sedikit detail daripada garis ringkasan dalam mendokumentasikan objek itu sendiri). Dokumentasi paket (mis., Modul yang didokumentasikan dalam __init__.py) juga harus menggambarkan dan mencantumkan modul dan sub paket yang diekspor oleh yang utama.

Dokumentasi fungsi atau metode harus menggambarkan perilaku, argumen, nilai balik, efek samping, pengecualian, dan batasan kapan mereka dapat dipanggil (jika ada). Anda juga harus menentukan argumen opsional. Harus diklarifikasi apakah argumen kunci adalah bagian dari antarmuka.

Dokumentasi kelas harus meringkas perilaku dan daftar metode publik serta variabel contohnya. Jika kelas akan memiliki subclass dengan antarmuka tambahan, maka antarmuka ini harus ditentukan secara terpisah (tetapi semuanya juga ada dalam dokumentasi ini). Konstruktor kelas harus memiliki jalur dokumentasi tersendiri untuk metode __init__. Metode independen (individu) harus memiliki dokumentasi sendiri.

Jika suatu kelas adalah turunan dan perilakunya sebagian besar diwarisi dari kelas utama, perlu untuk menyebutkan ini dalam dokumentasinya dan menggambarkan kemungkinan perbedaan. Gunakan kata kerja “override” untuk menunjukkan bahwa suatu metode telah diubah dan bahwa, sebagai hasilnya, metode superclass tidak akan dipanggil. Gunakan kata kerja "extends" jika metode subclass memanggil metode superclass (di samping perilakunya sendiri).

Jangan gunakan konvensi Emacs untuk menyebutkan argumen fungsi atau metode dalam huruf besar. Python peka huruf besar-kecil, dan nama argumen terkadang dapat digunakan saat melewatinya dengan kunci, jadi dokumentasi harus berisi nama variabel nyata. Yang terbaik adalah membuat daftar setiap argumen pada baris yang berbeda. Contohnya:

def complex(real=0.0, imag=0.0):
    """  .

     :
    real --   (  0.0)
    imag --   (  0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

Jika seluruh dokumen tidak cocok pada baris, Anda dapat menempatkan tanda kutip penutup pada baris yang terpisah. Dengan demikian, dimungkinkan untuk menggunakan perintah Emacs: fill-paragraf

Pemrosesan Docstring

Alat pengolah jalur dokumentasi harus menghapus jumlah indentasi yang sama dengan indentasi minimum dari semua saluran yang tidak kosong, mulai dari yang kedua. Lekukan apa pun pada baris pertama dokumentasi tidak signifikan dan akan dihapus. Indentasi relatif dari baris selanjutnya dalam baris dokumen dipertahankan. Baris kosong harus dihapus dari awal dan akhir baris dokumen.

Karena kode jauh lebih akurat daripada kata-kata, berikut adalah penerapan algoritme:

def trim(docstring):
    if not docstring:
        return ''
    #     (  Python)
    #      :
    lines = docstring.expandtabs().splitlines()
    #    (   ):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    #   (   ):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    #       :
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    #    :
    return '\n'.join(trimmed)

Catatan Penerjemah

, python3 sys.maxint sys.maxsize, .

Dokumentasi dalam contoh berikut berisi dua baris baru dan karenanya memiliki panjang tiga baris. Baris pertama dan terakhir kosong:

def foo ():
    """
       .
    """

Kami menggambarkan:

>>> print repr(foo.__doc__)
'\n        .\n    '
>>> foo.__doc__.splitlines()
['', '        .', '    ']
>>> trim(foo.__doc__)
'    .'

Dengan demikian, setelah diproses, baris dokumentasi berikut akan setara:

def foo():
    """ 
     .
    """

def bar():
    """
     
     .
    """