Dokumentasi (Comment, python doc tool)

 

Pendahuluan

Halo Mahasiswa Stupenss!

Selamat datang dalam materi yang menarik mengenai Dokumentasi (comment, python doc tool) dalam pengembangan Python backend. Dokumentasi adalah elemen krusial dalam pengembangan perangkat lunak, dan hal ini tidak kalah pentingnya dalam pengembangan backend menggunakan Python.

Dalam materi ini, kita akan menjelajahi berbagai konsep dan praktik yang terkait dengan dokumentasi dalam Python. Kita akan belajar cara menggunakan komentar untuk menjelaskan kode, menggunakan Python docstring untuk menghasilkan dokumentasi yang terstruktur, dan juga menggunakan alat bantu dokumentasi yang berguna.

Tetapi tunggu dulu! Materi ini tidak hanya akan memberikan penjelasan teoritis yang kaku. Sebagai gantinya, kita akan menjalani perjalanan interaktif yang melibatkan Anda secara langsung. Melalui contoh kode, tantangan, dan diskusi, Anda akan memiliki kesempatan untuk terlibat aktif dalam pembelajaran ini.

Jadi, bersiaplah untuk mendapatkan pemahaman yang mendalam tentang bagaimana membuat dokumentasi yang efektif, membantu Anda berkolaborasi dengan tim, meningkatkan kualitas kode Anda, dan menjadi pengembang backend Python yang lebih baik.

Dokumentasi itu Penting

"Kode lebih sering dibaca daripada ditulis."

Guido van Rossum

Ketika kamu menulis kode, kamu menulisnya untuk dua audiens utama: pengguna dan pengembang (termasuk dirimu sendiri). Kedua audiens tersebut sama pentingnya. Jika kamu seperti saya, mungkin pernah membuka kode lama dan bertanya-tanya, "Apa yang saya pikirkan saat itu?" Jika kamu kesulitan membaca kode kamu sendiri, bayangkan apa yang dirasakan oleh pengguna atau pengembang lain ketika mereka mencoba menggunakan atau berkontribusi pada kode kamu. Tapi tunggu dulu! Aku yakin kamu pernah mengalami situasi di mana kamu ingin melakukan sesuatu di Python dan menemukan pustaka yang tampak bagus yang dapat menyelesaikan tugas tersebut. Namun, begitu kamu mulai menggunakan pustaka tersebut, kamu mencari contoh, penjelasan, atau bahkan dokumentasi resmi tentang cara melakukan sesuatu secara spesifik dan tidak dapat segera menemukan solusinya.

Setelah mencari, kamu menyadari bahwa dokumentasinya kurang atau bahkan lebih buruk lagi, tidak ada sama sekali. Ini adalah perasaan frustrasi yang membuatmu enggan menggunakan pustaka tersebut, tidak peduli seberapa bagus atau efisien kode itu. Daniele Procida merangkum situasi ini dengan baik:

"Tidak peduli seberapa bagus perangkat lunak kamu, karena jika dokumentasinya tidak cukup baik, orang tidak akan menggunakannya."

Daniele Procida

Nah, di panduan ini, kamu akan belajar secara interaktif bagaimana mendokumentasikan kode Python kamu dengan baik, mulai dari skrip terkecil hingga proyek Python terbesar, untuk membantu mencegah pengguna kamu merasa frustasi saat menggunakan atau berkontribusi pada proyek kamu. Jadi, ayo kita mulai dan jelajahi dunia menarik dari dokumentasi dalam pengembangan backend Python!

Komentar dan dokumentasi kode

Komentar dan dokumentasi kode merupakan praktik penting dalam pengembangan perangkat lunak, namun keduanya memiliki tujuan dan konteks penggunaan yang berbeda.

Komentar mengacu pada penambahan komentar penjelasan di dalam kode itu sendiri. Komentar ini memberikan informasi tambahan tentang fungsionalitas kode, detail implementasi, atau wawasan penting lainnya. Komentar umumnya ditulis dalam bahasa alami dan ditujukan untuk dibaca dan dipahami oleh pengembang lain yang bekerja pada kode tersebut.

Tujuan utama dari komentar kode adalah:

1.    Klarifikasi: Komentar membantu menjelaskan tujuan dan logika di balik bagian bagian tertentu dari kode. Mereka dapat menjelaskan algoritma kompleks, memberikan konteks, atau menggambarkan perilaku yang diinginkan.

2.    Keterbacaan: Komentar yang ditempatkan dengan baik dapat meningkatkan keterbacaan keseluruhan kode. Mereka membuatnya lebih mudah bagi pengembang untuk memahami dan menjelajahi kode, terutama dalam proyek yang besar atau kompleks.

3.    Kolaborasi: Komentar memfasilitasi kolaborasi antara anggota tim. Mereka memungkinkan komunikasi yang efektif tentang kode, memungkinkan pengembang untuk mendiskusikan ide, menyarankan perbaikan, atau memberikan umpan balik.

Di sisi lain, mendokumentasikan kode melibatkan pembuatan dokumentasi eksternal yang memberikan gambaran menyeluruh tentang fungsionalitas perangkat lunak, API, petunjuk penggunaan, dan detail penting lainnya. Dokumentasi biasanya ditulis dalam format terstruktur, seperti docstring dalam Python, dan ditujukan untuk dikonsumsi oleh pengembang dan pengguna akhir.

Tujuan utama dari mendokumentasikan kode adalah:

1.    Panduan: Dokumentasi berfungsi sebagai panduan bagi pengembang dan pengguna, memberikan instruksi tentang cara menggunakan perangkat lunak, apa yang dilakukan setiap komponen, dan bagaimana berinteraksi dengan API atau pustaka. Ini membantu pengguna memahami kemampuan dan batasan perangkat lunak.

2.    Referensi: Dokumentasi berfungsi sebagai panduan referensi, memungkinkan pengembang dengan cepat mencari informasi tentang fungsi, kelas, atau modul tertentu. Dokumentasi memberikan detail tentang parameter, nilai kembalian, dan informasi lain yang diperlukan untuk menggunakan kode dengan efektif.

3.    Onboarding: Dokumentasi memainkan peran penting dalam memperkenalkan pengembang baru ke sebuah proyek. Dokumentasi memberikan pemahaman komprehensif tentang kode, struktur proyek, dan bagaimana berinteraksi antar komponen yang berbeda. Ini memungkinkan anggota tim baru untuk menjadi produktif lebih cepat.

Secara ringkas, komentar kode berfokus pada penambahan catatan penjelasan di dalam kode untuk meningkatkan keterbacaan dan memfasilitasi kolaborasi antar pengembang. Di sisi lain, mendokumentasikan kode melibatkan pembuatan dokumentasi eksternal yang berfungsi sebagai panduan dan referensi bagi pengembang dan pengguna. Kedua praktik tersebut penting untuk menciptakan perangkat lunak yang mudah dipelihara, dipahami, dan digunakan oleh pengguna.

 

 

Basic Commenting

Dasar-dasar dalam memberikan komentar pada kode adalah sebagai berikut:

1.    Penggunaan Tanda Pagar (#): Komentar dibuat di Python menggunakan tanda pagar (#) dan harus berupa pernyataan singkat yang tidak lebih dari beberapa kalimat. Berikut adalah contoh sederhana:

pythonCopy code

def hello_world():

# Komentar sederhana sebelum pernyataan print sederhana

print("Hello World")

2.    Panjang Komentar: Menurut PEP 8, komentar sebaiknya memiliki panjang maksimum 72 karakter. Hal ini berlaku bahkan jika proyek Anda mengubah batas panjang baris maksimum menjadi lebih dari 80 karakter yang direkomendasikan. Jika komentar akan melebihi batas karakter yang ditentukan, penggunaan beberapa baris untuk komentar adalah wajar.

pythonCopy code

def hello_long_world():

# Pernyataan yang sangat panjang yang terus berlanjut dan tidak pernah berakhir # sampai mencapai batas 80 karakter

print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

 

1. Tujuan Komentar: Memberikan komentar pada kode Anda memiliki beberapa tujuan, antara lain:

Perencanaan dan Peninjauan: Ketika Anda mengembangkan bagian baru dari kode, kadang-kadang merupakan keputusan yang tepat untuk menggunakan komentar sebagai cara untuk merencanakan atau menggambarkan bagian kode tersebut. Ingatlah untuk menghapus komentar ini setelah implementasi sebenarnya dari kode dan peninjauan/pengujian telah dilakukan.

Deskripsi Kode: Komentar dapat digunakan untuk menjelaskan tujuan dari bagian-bagian tertentu dari kode.

Deskripsi Algoritma: Ketika menggunakan algoritma, terutama yang kompleks, berguna untuk menjelaskan bagaimana algoritma tersebut bekerja atau diimplementasikan dalam kode Anda. Mungkin juga tepat untuk menjelaskan mengapa algoritma tertentu dipilih daripada yang lain.

Tagging: Penggunaan tagging dapat digunakan untuk memberi label pada bagian-bagian tertentu dari kode di mana terdapat masalah yang diketahui atau area yang perlu ditingkatkan. Beberapa contoh adalah: BUG, FIX ME, dan TODO.

2. Tetap Singkat dan Fokus: Komentar pada kode Anda harus singkat dan fokus. Hindari menggunakan komentar yang panjang jika memungkinkan. Selain itu, ikuti empat aturan penting berikut yang disarankan oleh Jeff Atwood:

Letakkan komentar sesuai dengan kode yang dijelaskan. Komentar yang tidak berdekatan dengan kode yang dijelaskan bisa membuat pembaca bingung dan mudah terlewat saat melakukan pembaruan.

Jangan gunakan format yang kompleks (seperti tabel atau gambar ASCII). Format yang kompleks akan membingungkan dan sulit dipelihara dari waktu ke waktu.

Jangan sertakan informasi yang redundan. Anggaplah pembaca kode memiliki pemahaman dasar tentang prinsip pemrograman dan sintaks bahasa.

Rancang kode Anda agar dapat menjelaskan dirinya sendiri. Cara termudah untuk memahami kode adalah dengan membacanya. Ketika Anda merancang kode menggunakan

konsep yang jelas dan mudah dipahami, pembaca akan dengan cepat dapat memahami tujuan Anda.Ingatlah bahwa komentar ditujukan untuk pembaca, termasuk diri Anda sendiri, untuk membantu memahami tujuan dan desain perangkat lunak.

Type Hinting

Type Hinting dalam Python memungkinkan kita memberikan komentar pada kode dengan menyertakan informasi tentang tipe data yang diharapkan dan tipe data yang dikembalikan oleh suatu fungsi. Dengan menggunakan Type Hinting, kita dapat memberikan penjelasan singkat dan jelas tentang tipe data yang digunakan dalam kode.

Misalnya, dengan menambahkan Type Hinting pada fungsi multiply seperti berikut:

pythonCopy code

def multiply(a: int, b: int) -> int:

return a * b

Dalam contoh ini, Type Hinting mengindikasikan bahwa parameter a dan b diharapkan sebagai bilangan bulat ( int ), dan fungsi ini akan mengembalikan hasil perkalian yang juga merupakan bilangan bulat ( int ).

Type Hinting dapat membantu pengembang lain atau bahkan diri sendiri untuk memahami tipe data yang diharapkan oleh suatu fungsi. Namun, penting untuk diingat bahwa Type Hinting bukan pengganti komentar yang menjelaskan logika dan tujuan dari kode secara verbal. Keduanya dapat digunakan bersama-sama untuk memberikan dokumentasi yang lebih lengkap dan membantu pengguna lain dalam memahami dan menggunakan kode dengan benar.

Docstring

Docstring merupakan cara lain yang berguna untuk mendokumentasikan kode Python Anda. Docstring adalah string yang ditempatkan pada awal sebuah fungsi, kelas, atau modul Python yang berfungsi sebagai dokumentasi untuk entitas tersebut. Docstring dapat berisi deskripsi, contoh penggunaan, parameter, nilai balik, dan informasi penting lainnya tentang kode yang Anda tulis.

Berikut adalah contoh penggunaan docstring pada sebuah fungsi:

 

pythonCopy code

def multiply(a, b):

"""Mengalikan dua bilangan dan mengembalikan hasilnya.

Parameters:

a (int): Bilangan pertama.

b (int): Bilangan kedua.

Returns:

int: Hasil perkalian dari a dan b.

"""

return a * b

Pada contoh di atas, docstring ditempatkan di dalam tiga tanda kutip ganda ( """ ). Docstring menjelaskan dengan jelas tujuan fungsi, parameter yang diterima (beserta tipe datanya), dan nilai balik yang dihasilkan. Ini membantu pengguna lain untuk memahami cara menggunakan fungsi ini dengan benar.

Selain itu, Anda juga dapat menggunakan docstring pada kelas dan modul Python. Docstring pada kelas menjelaskan tujuan, atribut, dan metode yang dimiliki oleh kelas tersebut. Sedangkan docstring pada modul memberikan deskripsi tentang isi dan fungsionalitas modul tersebut.

Penting untuk menulis docstring yang informatif, jelas, dan konsisten. Docstring yang baik dapat membantu dalam pemeliharaan kode, kolaborasi dengan pengembang lain, serta membantu Anda mengingat dan memahami kode yang telah ditulis di masa mendatang.

 

Untuk mengakses docstring dari suatu fungsi, kelas, atau modul dalam kode Python, Anda dapat menggunakan fungsi bawaan help() . Dengan menjaga docstring yang terorganisir dan terdokumentasi dengan baik, Anda dapat memperkaya pengalaman pengguna dan memudahkan orang lain untuk bekerja dengan kode yang Anda tulis.

Contoh Implementasi

Berikut adalah contoh implementasi dokumentasi kode dengan menggunakan docstring pada sebuah fungsi Python:

pythonCopy code

def calculate_rectangle_area(length, width):

"""Calculate the area of a rectangle.

This function takes the length and width of a rectangle as parameters and returns the calculated area.

Parameters:

length (float): The length of the rectangle.

width (float): The width of the rectangle.

Returns:

float: The calculated area of the rectangle.

"""

area = length * width

return area

Pada contoh diatas, kita memiliki fungsi calculate_rectangle_area yang menghitung luas suatu persegi panjang. Docstring yang ditempatkan di dalam tiga tanda kutip ganda menjelaskan dengan jelas tujuan fungsi ini, parameter yang diterima (beserta tipe datanya), dan nilai balik yang dihasilkan.

Dengan menggunakan docstring seperti ini, pengguna fungsi ini dapat dengan mudah memahami cara menggunakannya dengan benar. Selain itu, docstring juga memberikan petunjuk kepada pengguna bahwa fungsi ini membutuhkan dua argumen berupa panjang ( length ) dan lebar ( width ) dalam bentuk bilangan pecahan ( float ).

Anda juga dapat menggunakan fungsi bawaan help() untuk mengakses docstring dari fungsi ini. Misalnya:

pythonCopy code

help(calculate_rectangle_area)

 

Outputnya akan menampilkan dokumentasi yang telah kita buat:

sqlCopy code

Help on function calculate_rectangle_area in module __main__:

calculate_rectangle_area(length, width)

Calculate the area of a rectangle.

This function takes the length and width of a rectangle as parameters and returns the calculated area.

Parameters:

length (float): The length of the rectangle.

width (float): The width of the rectangle.

Returns:

float: The calculated area of the rectangle.

 

Dengan adanya dokumentasi yang jelas dan terdokumentasi dengan baik seperti ini, pengguna lain dapat dengan mudah memahami dan menggunakan fungsi ini dalam kode mereka.

Quiz

1. Apa tujuan dari penggunaan docstring pada kode Python?

a) Memberikan penjelasan detail tentang algoritma yang digunakan dalam kode. b) Menambahkan komentar untuk memperindah tampilan kode. c) Memberikan dokumentasi yang jelas tentang fungsi, kelas, atau modul Python.

d) Menggantikan komentar dalam kode untuk menjelaskan logika program.

2. Apa yang dimaksud dengan docstring?

a) Sebuah tipe data dalam Python untuk mendokumentasikan string. b) Sebuah sintaks khusus untuk menuliskan komentar dalam kode Python. c) Sebuah string yang ditempatkan di awal fungsi, kelas, atau modul Python yang berfungsi sebagai dokumentasi.

d) Sebuah metode untuk mengakses dokumen resmi Python.

3. Apa yang bisa dimasukkan dalam docstring?

a) Deskripsi tentang tujuan fungsi, parameter, dan nilai balik.

b) Contoh penggunaan fungsi.

c) Informasi tentang tipe data parameter dan nilai balik.

d) Semua jawaban di atas.

4. Bagaimana cara mengakses docstring dari sebuah fungsi?

a) Dengan menggunakan fungsi help() .

b) Dengan menggunakan metode docstring() pada objek fungsi. c) Dengan menggunakan fungsi print() untuk mencetak docstring. d) Docstring tidak bisa diakses dari fungsi.

5. Apa manfaat dari menggunakan docstring dalam kode Python? a) Membantu pengembang lain memahami fungsionalitas kode. b) Meningkatkan kecepatan eksekusi kode.

c) Membuat kode lebih pendek dan efisien.

d) Menggantikan komentar dalam kode.

Referensi

https://realpython.com/documenting-python-code/#documenting-your-python-code base-using-docstrings

https://realpython.com/courses/building-project-documentation-mkdocs/ https://realpython.com/courses/python-sphinx/

https://flask

diamond.readthedocs.io/en/stable/developer/writing_documentation_with_sphinx/

Dokumentasi (Comment, python doc tool) 10