Cara Mendokumentasikan Kode Python

Jika Anda baru mulai belajar Python dan ingin mengetahui lebih lanjut, ikuti kursus Intermediate Python dari DataCamp.

Relevansi Mendokumentasikan Proyek Anda

Dokumentasi adalah bagian penting dari proyek apa pun yang Anda kerjakan, terlepas dari bahasa pemrograman yang digunakan. Sebuah proyek dengan aplikasi yang terdiri dari berbagai API yang berjalan dan digunakan banyak pengguna tetapi tanpa dokumentasi akan dianggap tidak lengkap. Bayangkan sejenak Anda sebagai pengembang: bagaimana perasaan Anda jika ingin mereplikasi sebuah proyek atau menggunakan sebagian aspek dari proyek yang tidak memiliki dokumentasi? Pastinya Anda akan kesulitan mengintegrasikannya ke dalam arsitektur Anda.

Dokumentasi yang lebih baik akan membuat proyek Anda lebih berhasil karena saat Anda membagikan proyek atau perangkat lunak ke dunia, Anda ingin orang-orang menggunakannya. Terutama ketika itu adalah proyek open-source, tujuannya akan semakin besar. Anda juga ingin komunitas berkontribusi pada proyek Anda dan membuatnya lebih baik.

Penulis terkenal bahasa pemrograman Python pernah mengutip bahwa Code is more often read than written. Kutipan ini menyoroti betapa pentingnya dokumentasi bagi kode atau proyek Anda agar dapat diimplementasikan oleh orang lain.

Bayangkan diri Anda sebagai karyawan di perusahaan XYZ, Anda sedang menjalani masa pemberitahuan, dan manajer Anda ingin Anda menyerahkan proyek tersebut kepada rekan kerja. Anda mungkin memberikan KT (knowledge transfer), tetapi bagaimana jika rekan Anda gagal mengeksekusi salah satu kode dari proyek tersebut dengan sukses? Ada beberapa alasan mengapa kode tidak berjalan, mungkin biner yang dijalankan oleh kode Anda tidak cocok dengan biner dari OS saat ini.

Apa sebenarnya yang dimaksud dengan Dokumentasi?

Dokumentasi memiliki beberapa komponen. Dokumentasi perlu ditata dengan baik di sekitar komponen-komponen ini dan mematuhinya agar dapat dianggap sebagai dokumentasi yang layak.

Secara abstrak, komponennya meliputi:

• Memastikan basis kode proyek Anda memiliki komentar yang baik.

• Mematuhi standar pengkodean PEP-8 Python.

• Tutorial konkret tentang bagaimana proyek dibangun, terutama ketika ini adalah proyek open-source yang dikembangkan untuk tujuan pembelajaran.

• Panduan cara memasang paket dan modul yang diperlukan untuk membangun perangkat lunak, lembar spesifikasi teknis jika proyek juga mencakup perangkat keras. Misalnya, cara memasang anaconda, TensorFlow, Keras, dan sebagainya.

• Berbagai diskusi tentang kemajuan proyek pada setiap langkah waktu yang dapat mengarah pada keberhasilan implementasi perangkat lunak.

• Materi referensi yang memberikan deskripsi teknis tentang tumpukan teknologi yang digunakan selama fase pengembangan.

• Desain arsitektur dari proyek atau solusi perangkat lunak.

Poin-poin ini hanyalah sebagian dari komponen yang dapat ada dalam dokumen yang tertata baik dan tampak sempurna. Penting untuk menjaga semua komponen ini tetap berbeda, yang juga akan memudahkan pemeliharaan dokumentasi di masa mendatang.

Contoh dokumentasi komprehensif yang memiliki sebagian besar komponen yang kita bahas akan serupa dengan yang ditunjukkan di bawah ini:

Banyak orang sering bingung antara commenting & documenting dan menganggap keduanya serupa. Komentar digunakan untuk menjelaskan kode Anda kepada pengguna, pemelihara, dan bahkan untuk diri Anda sendiri sebagai referensi di masa depan. Komentar hanya berfungsi pada level kode dan dapat dikategorikan sebagai subset dari dokumentasi. Komentar membantu pembaca untuk:

• memahami kode Anda,
• membuatnya mudah dipahami sendiri, dan
• memahami tujuan dan desainnya.

Penting untuk diingat bahwa karena Python mengikuti standar pengkodean PEP-8, komentar pun harus mematuhi standar tersebut. Dokumentasi resmi Python menyatakan bahwa untuk blok teks panjang dengan pembatasan struktural yang lebih sedikit (docstring atau komentar), panjang baris harus dibatasi hingga 72 karakter.

Untuk memeriksa apakah kode Anda mematuhi standar PEP-8, Anda dapat menggunakan modul Python pylint. Modul ini dapat digunakan untuk mengubah batas karakter untuk komentar dan semua baris kode lainnya.

Mari lihat beberapa contoh.

• Deskripsi impor modul

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Deskripsi pendefinisian variabel

n_classes = 10 # MNIST total classes (0-9 digits)

Untuk pemahaman yang lebih mendalam tentang komentar serta yang boleh dan tidak boleh dilakukan, lihat tulisan yang bermanfaat ini.

Sekarang mari pelajari bagaimana docstring dapat membantu dalam mendokumentasikan basis kode proyek Anda.

Docstring untuk Mendokumentasikan Kode Python

Python Docstring adalah string dokumentasi berupa string literal yang muncul dalam definisi kelas, modul, fungsi, atau metode, dan ditulis sebagai pernyataan pertama. Docstring dapat diakses dari atribut doc (__doc__) untuk objek Python apa pun, dan juga dapat dimanfaatkan dengan fungsi bawaan help().

Selain itu, Docstring sangat berguna untuk memahami fungsionalitas bagian kode yang lebih besar, yaitu tujuan umum dari kelas, modul, atau fungsi apa pun. Sebaliknya, komentar digunakan untuk kode, pernyataan, dan ekspresi, yang cenderung kecil. Komentar adalah teks deskriptif yang ditulis oleh pemrogram terutama untuk diri mereka sendiri agar mengetahui apa yang dilakukan baris kode atau ekspresi tersebut dan juga untuk pengembang yang ingin berkontribusi pada proyek tersebut. Ini adalah bagian penting karena mendokumentasikan kode Anda akan sangat membantu dalam menulis kode yang bersih dan program yang tertulis dengan baik. Meskipun sudah disebutkan, tidak ada standar dan aturan baku untuk melakukannya.

Ada dua bentuk penulisan Docstring: Docstring satu baris dan Docstring multi-baris. Inilah dokumentasi yang digunakan oleh Data Scientist/pemrogram dalam proyek mereka.

• Docstring satu baris adalah Docstring yang muat dalam satu baris. Anda dapat menggunakan salah satu tanda kutip, yaitu tiga kutip tunggal atau tiga kutip ganda; tanda kutip pembuka dan penutup harus sama. Pada Docstring satu baris, tanda kutip penutup berada di baris yang sama dengan tanda kutip pembuka. Konvensi standar adalah menggunakan tiga kutip ganda.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Docstring multi-baris juga berisi baris literal string yang sama seperti pada Docstring satu baris, tetapi diikuti oleh satu baris kosong bersama teks deskriptif.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Dari tabel di atas, mari pilih Pydoc sebagai salah satu format docstring dan mengeksplorasinya lebih lanjut.

Seperti yang Anda ketahui, docstring dapat diakses melalui atribut bawaan Python __doc__ dan fungsi help(). Anda juga dapat menggunakan modul bawaan yang dikenal sebagai Pydoc, yang sangat berbeda dari segi fitur dan fungsionalitasnya jika dibandingkan dengan atribut doc dan fungsi help.

Pydoc adalah alat yang berguna saat Anda ingin membagikan kode kepada rekan kerja atau membuatnya menjadi open-source, di mana Anda menargetkan audiens yang jauh lebih luas. Pydoc dapat menghasilkan halaman web dari dokumentasi Python Anda dan juga dapat meluncurkan server web.

Mari lihat cara kerjanya.

Cara termudah dan paling nyaman untuk menjalankan modul Pydoc adalah menjalankannya sebagai skrip. Untuk menjalankannya di dalam sel jupyter lab, Anda akan menggunakan karakter tanda seru (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Jika Anda melihat keluaran di atas, penggunaan pertama Pydoc adalah menampilkan dokumentasi teks untuk fungsi, modul, kelas, dan sebagainya. Mari lihat bagaimana Anda dapat memanfaatkannya dengan lebih baik daripada fungsi help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Sekarang, mari ekstrak dokumentasi glob menggunakan fungsi help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Nah, seperti yang Anda lihat, muncul name error karena glob belum didefinisikan. Jadi agar Anda dapat menggunakan fungsi help untuk mengekstrak dokumentasi, Anda harus terlebih dahulu mengimpor modul tersebut, yang tidak berlaku pada Pydoc.

Mari kita jelajahi fitur paling menarik dari modul Pydoc, yaitu menjalankan Pydoc sebagai layanan web.

Untuk melakukan ini, Anda cukup menjalankan Pydoc sebagai skrip tetapi dengan argumen -b yang akan memulai server HTTP pada port kosong yang dipilih secara acak dan membuka peramban web untuk menelusuri dokumentasi secara interaktif. Ini sangat membantu, terutama ketika Anda memiliki berbagai layanan lain yang berjalan di sistem Anda, dan Anda tidak ingat port mana yang sedang tidak digunakan.

!python -m pydoc -b

^C

Saat Anda menjalankan sel di atas, jendela baru akan terbuka pada nomor port acak, dan peramban web akan tampak seperti yang ditunjukkan di bawah ini.

Mari lihat dokumentasi modul h5py, yang merupakan format berkas untuk menyimpan bobot arsitektur jaringan saraf.

Hal-hal Esensial saat Mendokumentasikan Proyek Python

Terlepas dari tujuan, visi, dan maksud proyek, dokumentasi setiap proyek kurang lebih tetap sama. Proyek dapat masuk ke dalam kategori berikut:

• Proyek Privat (pribadi): Bisa untuk membangun portofolio atau bekerja sebagai freelancer yang memelihara repositori GitHub.

• Proyek Kolaboratif (tim): Bisa berupa proyek yang dijalankan di organisasi Anda atau mengerjakan kompetisi Kaggle.

• Proyek Open-source: Proyek open-source terutama berfokus pada pembagian kepada audiens luas. Mengharapkan kolaborasi, kontribusi, dan keterpeliharaan basis kode serta dokumentasi dalam jangka panjang.

Walaupun ketiga kategori proyek di atas memiliki visi yang berbeda, templat dokumentasinya dapat dibagikan di semua jenis proyek.

Misalkan Anda mengerjakan proyek open-source dan diminta membuat repositori GitHub untuk itu yang harus memiliki dokumentasi rinci dan diperbarui secara berkala, berikut poin-poin penting yang perlu Anda ingat:

• Berkas requirements: Sering kali penulis lupa akan hal ini, padahal berkas requirements sangat penting. Ini membantu pengguna mereproduksi kode Anda dengan cepat. Biasanya berupa berkas teks yang memuat semua paket, modul beserta versi masing-masing yang digunakan dalam proyek. Requirements bahkan bisa disebutkan di berkas Readme, tetapi memilikinya secara terpisah selalu lebih baik karena pengguna bisa langsung menjalankan berkas itu dengan perintah pip, dan semua dependensi akan dipasang di sistem masing-masing.

• Readme: Berkas Readme biasanya menggunakan format markdown, yang juga menjadi tulang punggung bagi banyak proyek. Ringkasan proyek, fitur, dan tujuannya dengan logo yang bagus. Berisi instruksi untuk memasang atau mengoperasikan proyek. Selain itu, tambahkan perubahan signifikan sejak versi sebelumnya. Skrip pengujian atau tur singkat untuk menjalankan kode mereka dengan sukses dalam Readme memberikan kepercayaan lebih kepada pengguna untuk menindaklanjuti proyek Anda. Readme juga dapat menyoroti potensi masalah yang mungkin dihadapi pengguna.

• Cara Berkolaborasi: Ini penting, terutama saat Anda mengerjakan proyek open-source. Bagian ini harus mencakup bagaimana kolaborator baru dapat berkontribusi pada proyek. Ini termasuk mengembangkan fitur baru, memperbaiki bug yang diketahui, menambahkan dokumentasi, menambahkan pengujian baru, atau melaporkan isu. Kolaborator bahkan dapat merilis v2.0 dari proyek yang sama dan membawa proyek ke level yang lebih tinggi.

• Lisensi: Berkas teks biasa yang menjelaskan lisensi yang digunakan proyek Anda. Sangat krusial untuk proyek open-source, seperti lisensi Boost, Apache, MIT, dan lain-lain. Ini memberi tahu pengguna apakah proyek bebas digunakan secara komersial atau sampai sejauh mana.

• Penugasan tugas: Jika Anda mengerjakan proyek bersama seperti Kaggle, Anda dapat mendefinisikan tugas yang diberikan kepada setiap anggota dan tingkat kemajuan tugas. Ini membantu melacak kemajuan keseluruhan yang dicapai dalam proyek.

• Kebergunaan ulang kerangka kerja: Ini berperan penting dalam proyek bersama seperti Kaggle di mana rekan tim Anda dapat menggunakan kembali apa yang mungkin telah Anda bangun, yang dapat menghemat banyak waktu. Misalnya, pipeline prapemrosesan data, skrip validasi silang data, dan sebagainya.

Dokumentasi yang sangat direkomendasikan, tertata sangat baik, dan berpotensi menjadi contoh sempurna bagaimana seharusnya proyek open-source terlihat adalah repositori GitHub huggingface transformers.

Kesimpulan

Selamat telah menyelesaikan tutorial ini.

Salah satu latihan yang baik bagi Anda semua adalah mengeksplorasi modul Pydoc lebih jauh dan format docstring Python lainnya seperti Epydoc dan Google docstrings serta mencari tahu bagaimana perbedaannya satu sama lain.

Jangan ragu untuk mengajukan pertanyaan terkait tutorial ini di kolom komentar di bawah.

Referensi:

• Docstring di Python

Jika Anda baru mulai belajar Python dan ingin mengetahui lebih lanjut, ikuti kursus Intermediate Python dari DataCamp.