Dokstring Python

Dokumentasi sangat penting untuk pengaturcaraan untuk memahami kod dengan mudah. Ia digunakan untuk menjelaskan tujuan penggunaan pernyataan atau fungsi atau kelas atau modul dalam program. Ini membantu pengekod utama mengingat fungsi kod apa pun setelah sekian lama, dan juga membantu pengekod lain yang ingin mengerjakan projek yang sama. Pengekod menggunakan satu baris komen untuk menerangkan bahagian fungsi kod tersebut sebentar lagi. String dokumen Python atau docstring digunakan untuk menjelaskan fungsi segmen kod tertentu secara terperinci. Garis dokumen harus bermula dengan huruf besar dan diakhiri dengan noktah. Baris pertama dokumen mengandungi penerangan ringkas mengenai dokumentasi secara amnya. Baris kedua docstring harus kosong untuk docstring multi-line besar. Petikan tunggal tiga ('”) atau petikan tiga kali ganda ("" ") digunakan untuk menentukan docstring di Python. Kandungan dokumen boleh diakses dengan menggunakan __doc__ atribut objek dan menggunakan pertolongan () kaedah. Cara menyatakan dan mengakses docstring di Python telah ditunjukkan dalam tutorial ini.

Contoh-1: Mengakses docstring fungsi menggunakan __doc__ atribut

Cara menyatakan dan mengakses dokstring fungsi kustom telah ditunjukkan dalam skrip berikut. Skrip berikut mengira xⁿ di mana x dan n akan diambil dari pengguna. Kuasa () fungsi telah ditentukan dalam skrip untuk melakukan tugas. Di sini, docstring telah ditentukan untuk fungsi ini. __doc__ atribut telah digunakan dalam skrip untuk mencetak dokumen dengan output.

daya def (x, n):
"Kira x hingga daya n
Baca nilai x dan n dari argumen fungsi
dan Kira dan kembalikan nilai x ke daya n."
pulangan x ** n
# Ambil nilai x
x = int (input ('Masukkan nilai x:'))
# Ambil nilai n
n = int (input ('Masukkan nilai n:'))
# Cetak nilai pengembalian fungsi
cetak ("% d hingga kuasa% d =% d"% (x, n, daya (x, n)))
# Cetak nilai dokumen
cetak ("Isi dokumen: \ n" + kuasa.__doc__)

Pengeluaran:

Output berikut akan muncul setelah menjalankan skrip di atas.

Contoh-2: Mengakses docstring kelas dan kaedah menggunakan pertolongan () kaedah

Cara menyatakan dan mengakses dokumen dokumen dan kaedah kelas tersebut telah ditunjukkan dalam skrip berikut. Fungsi utama skrip adalah menyusun senarai angka dan membalikkan data senarai. Senarai angka 8 elemen telah dinyatakan di dalam kelas, dan dokstring telah ditentukan pada awal kelas dengan menggunakan petikan tunggal tiga. Kaedah sort_list () telah ditentukan di kelas untuk mencetak data yang disusun dari senarai, dan dokumen telah menentukan ini untuk kaedah ini. senarai_balik () kaedah didefinisikan untuk mencetak data terbalik senarai, dan docstring juga telah ditentukan untuk kaedah ini. pertolongan () kaedah telah memanggil tiga kali pada akhir skrip untuk mencetak dokumen list_operations kelas, urutkan_ senarai () kaedah, dan senarai_balik () kaedah.

senarai_ operasi kelas:

senarai_ operasi kelas:
"
Menyusun dan membalikkan data senarai
Kelas mengandungi dua kaedah,
kaedah sort_list () akan menyusun dan mencetak senarai,
kaedah sort_reverse () akan membalikkan dan mencetak senarai.
"
# Tentukan senarai data berangka
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (diri):
"
Cetak nilai senarai selepas menyusun
Fungsi akan mengambil objek senarai data berangka dari argumen,
susun nilai senarai menggunakan kaedah sort ()
dan mencetak nilai senarai yang disusun.
"
# Susun senarai
diri.senarai data.urutkan ()
# Cetak senarai yang disusun menggunakan gelung
cetak ("Nilai senarai yang disusun: \ n")
untuk nilai dalam diri.senarai data:
cetak (nilai, "", akhir = ")
def reverse_list (diri):
"
Cetak nilai senarai setelah membalikkan
Fungsi akan mengambil objek senarai data berangka dari argumen,
membalikkan nilai senarai menggunakan kaedah terbalik ()
dan mencetak nilai senarai terbalik.
"
# Balikkan senarai
diri.senarai data.terbalik ()
# Cetak senarai terbalik menggunakan gelung
cetak ("Nilai senarai yang disusun: \ n")
untuk nilai dalam diri.senarai data:
cetak (nilai, "", akhir = ")
# Cetak nilai docstring kelas
pertolongan (list_operations)
# Buat objek kelas
obj = list_operations ()
# Cetak nilai dokumen kaedah tertentu
pertolongan (obj.urutkan_ senarai)
# Hubungi kaedah untuk mencetak senarai yang disusun
obj.urutkan_ senarai ()

Pengeluaran:

Output berikut akan muncul setelah melaksanakan skrip. Semua dokumentasi skrip telah dicetak untuk yang pertama pertolongan () fungsi. Dokumentasi dari urutkan_ senarai () kaedah telah dicetak untuk yang kedua pertolongan () fungsi.

Contoh-3: Mengakses dokstring modul Python terbina dalam

Dalam contoh sebelumnya, docstring telah digunakan dalam kelas dan fungsi yang ditentukan pengguna. Setiap modul dan kelas Python yang ada mempunyai penyusun dokumen yang menerangkan tujuan penggunaan modul atau fungsi tersebut. Pengkod modul atau fungsi menentukan docstring untuk menjadikan kod itu dapat difahami oleh pengguna. Skrip berikut akan mencetak docstring yang telah ditentukan dari modul datetime dengan menggunakan pertolongan () fungsi.

# Modul import masa
masa data import
# Paparkan dokumentasi datetime
pertolongan (masa masa)

Pengeluaran:

Output berikut akan muncul setelah menjalankan skrip. Dokumentasi modul datetime menunjukkan dokumentasi terperinci untuk membantu yang lain mengetahui fungsi kelas dan kaedah yang ditentukan dalam modul ini dengan betul.

Kesimpulan:

Dokumentasi yang betul sangat mustahak apabila modul atau fungsi apa pun dilaksanakan untuk tujuan tertentu untuk membantu pengkod lain menggunakan modul dalam kod mereka untuk melakukan tugas tertentu. Sekiranya dokumentasi tidak ditentukan dengan tepat untuk modul atau fungsi, pengguna lain akan menghadapi masalah menggunakannya. Oleh itu, setiap pengekod harus menggunakan dokumentasi dokumen untuk memberikan maklumat terperinci agar orang lain dapat memahami kod tersebut.