Buat Komentar Python dengan Cara yang Benar

Komentar adalah catatan bahwa pemrogram mengiklankan kode mereka untuk menjelaskan apa yang seharusnya dilakukan oleh kode tersebut. Kompiler atau juru bahasa yang mengubah kode menjadi tindakan mengabaikan komentar, tetapi komentar dapat menjadi penting untuk mengelola proyek perangkat lunak.

Komentar membantu menjelaskan kode Python Anda kepada pemrogram lain dan dapat mengingatkan Anda mengapa Anda membuat pilihan yang Anda lakukan. Komentar mempermudah proses debug dan merevisi kode dengan membantu pemrogram masa depan memahami pilihan desain di balik perangkat lunak.

Meskipun komentar terutama untuk pengembang, menulis komentar yang efektif juga dapat membantu menghasilkan dokumentasi yang sangat baik untuk pengguna kode Anda. Dengan bantuan pembuat dokumen seperti proyek Sphinx untuk Python, komentar dalam kode Anda dapat menyediakan konten untuk dokumentasi Anda.

Mari kita lihat di balik komentar dengan Python.

Komentar dengan Python

Menurut Panduan Gaya Python PEP 8, ada beberapa hal yang perlu diingat saat menulis komentar:

• Komentar harus selalu berupa kalimat yang lengkap dan ringkas.
• Lebih baik tidak memiliki komentar sama sekali daripada komentar yang sulit dipahami atau tidak akurat.
• Komentar harus diperbarui secara berkala untuk mencerminkan perubahan pada kode Anda.
• Terlalu banyak komentar dapat mengganggu dan mengurangi kualitas kode. Komentar tidak diperlukan jika tujuan kode sudah jelas.

Dalam Python, sebuah baris dideklarasikan sebagai komentar ketika dimulai dengan simbol # . Ketika juru bahasa Python menemukan # dalam kode Anda, itu mengabaikan apa pun setelah simbol itu dan tidak menghasilkan kesalahan apa pun. Ada dua cara untuk mendeklarasikan komentar satu baris: komentar sebaris dan memblokir komentar.

Komentar Sebaris

Komentar sebaris memberikan deskripsi singkat tentang variabel dan operasi sederhana dan ditulis pada baris yang sama dengan pernyataan kode:

 border = x + 10 # Make offset of 10px

Komentar menjelaskan fungsi kode dalam pernyataan yang sama dengan kode.

Blokir Komentar

Komentar blok digunakan untuk menggambarkan logika kompleks dalam kode. Blokir komentar di Python dibangun serupa dengan komentar sebaris — satu-satunya perbedaan adalah bahwa komentar blokir ditulis pada baris terpisah:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Perhatikan bahwa saat menggunakan komentar blokir, komentar ditulis di atas kode yang dijelaskan. Panduan Gaya Python PEP8 menetapkan bahwa satu baris kode tidak boleh berisi lebih dari tujuh puluh sembilan karakter, dan komentar sebaris sering mendorong baris sepanjang ini. Inilah sebabnya mengapa komentar blok ditulis untuk mendeskripsikan kode pada baris terpisah.

Komentar Multi-Baris

Python tidak mendukung komentar multi-baris, yang berarti tidak ada ketentuan khusus untuk mendefinisikannya. Meskipun demikian, komentar yang mencakup banyak baris sering digunakan.

Anda dapat membuat komentar multi-baris dari beberapa komentar satu baris dengan mengawali setiap baris dengan # :

 # interpreter # ignores # these lines

Anda juga dapat menggunakan sintaks string multi-baris. Dengan Python, Anda dapat mendefinisikan string multi-baris dengan menyertakannya dalam """ , tanda kutip ganda tiga, atau ''' , tanda kutip tunggal tiga:

 print("Multi-Line Comment") """ This String is Multi line """

Pada kode di atas, string multi-baris tidak ditugaskan ke variabel, yang membuat string berfungsi seperti komentar. Saat runtime, Python mengabaikan string, dan tidak disertakan dalam bytecode. Mengeksekusi kode di atas menghasilkan keluaran berikut:

 Multi-Line Comment

Komentar Khusus

Selain membuat kode Anda dapat dibaca, komentar juga melayani beberapa tujuan khusus di Python, seperti merencanakan penambahan kode di masa mendatang dan menghasilkan dokumentasi.

Komentar Docstring Python

Dalam Python, docstring adalah komentar multi-baris yang menjelaskan cara menggunakan fungsi atau kelas tertentu. Dokumentasi kode Anda ditingkatkan dengan pembuatan dokumen berkualitas tinggi. Saat bekerja dengan fungsi atau kelas dan menggunakan fungsi help(obj) bawaan, docstrings mungkin berguna dalam memberikan ikhtisar objek.

Python PEP 257 menyediakan metode standar untuk mendeklarasikan docstring dengan Python, ditunjukkan di bawah ini:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

Dalam kode di atas, docstring memberikan detail tentang cara kerja fungsi terkait. Dengan generator dokumentasi seperti Sphinx, docstring ini dapat digunakan untuk memberikan ikhtisar kepada pengguna proyek Anda tentang cara menggunakan metode ini.

Docstring yang ditentukan tepat di bawah fungsi atau tanda tangan kelas juga dapat dikembalikan dengan menggunakan fungsi help() bawaan. Fungsi help() mengambil objek atau nama fungsi sebagai argumen, dan mengembalikan docstring fungsi sebagai output. Pada contoh di atas, help(get_person) dapat dipanggil untuk mengungkapkan dokumen yang terkait dengan fungsi get_person . Jika Anda menjalankan kode di atas dalam shell interaktif menggunakan flag -i , Anda dapat melihat bagaimana docstring ini akan diuraikan oleh Python. Jalankan kode di atas dengan mengetikkan python -i file.py .

Panggilan fungsi help(get_person) mengembalikan sebuah docstring untuk fungsi Anda. Outputnya berisi get_person(name, age, d=False) , yang merupakan tanda tangan fungsi yang ditambahkan Python secara otomatis.

get_person.__ doc__ juga dapat digunakan untuk mengambil dan memodifikasi docstring secara terprogram. Setelah menambahkan “Some more new information” pada contoh di atas, muncul pada panggilan kedua ke help(get_person) . Namun, sepertinya Anda tidak perlu mengubah dokumen secara dinamis saat runtime seperti ini.

Komentar TODO

Saat menulis kode, ada kalanya Anda ingin menyorot baris tertentu atau seluruh blok untuk perbaikan. Tugas ini ditandai oleh komentar TODO. Komentar TODO berguna saat Anda merencanakan pembaruan atau perubahan pada kode Anda, atau jika Anda ingin memberi tahu pengguna atau kolaborator proyek bahwa bagian tertentu dari kode file masih harus ditulis.

Komentar TODO tidak boleh ditulis sebagai pseudocode — mereka hanya perlu menjelaskan secara singkat fungsi dari kode yang belum ditulis.

Komentar TODO dan komentar blok satu baris sangat mirip, dan satu-satunya perbedaan di antara keduanya adalah bahwa komentar TODO harus dimulai dengan awalan TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Penting untuk dicatat bahwa meskipun banyak IDE dapat menyorot komentar ini untuk pemrogram, juru bahasa Python tidak melihat komentar TODO secara berbeda dari komentar blokir.

Praktik Terbaik Saat Menulis Komentar Python

Ada sejumlah praktik terbaik yang harus diikuti saat menulis komentar untuk memastikan keandalan dan kualitas. Di bawah ini adalah beberapa tip untuk menulis komentar berkualitas tinggi dengan Python.

Hindari Yang Jelas

Komentar yang menyatakan hal yang sudah jelas tidak menambah nilai apa pun pada kode Anda, dan harus dihindari. Sebagai contoh:

 x = x + 4 # increase x by 4

Komentar itu tidak berguna, karena hanya menyatakan apa yang dilakukan kode tanpa menjelaskan mengapa hal itu perlu dilakukan. Komentar harus menjelaskan "mengapa" daripada "apa" dari kode yang mereka gambarkan.

Ditulis ulang dengan lebih bermanfaat, contoh di atas mungkin terlihat seperti ini:

 x = x + 4 # increase the border width

Pertahankan Komentar Python Singkat dan Manis

Buat komentar Anda singkat dan mudah dipahami. Mereka harus ditulis dalam prosa standar, bukan pseudocode, dan harus menggantikan kebutuhan untuk membaca kode aktual untuk mendapatkan gambaran umum tentang fungsinya. Terlalu banyak detail atau komentar yang rumit tidak membuat pekerjaan programmer menjadi lebih mudah. Sebagai contoh:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Komentar di atas memberikan lebih banyak informasi daripada yang diperlukan bagi pembaca. Alih-alih menentukan logika inti, komentar harus memberikan ringkasan kode secara umum. Komentar ini dapat ditulis ulang sebagai:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Gunakan Pengidentifikasi dengan Hati-hati

Pengidentifikasi harus digunakan dengan hati-hati dalam komentar. Mengubah nama atau kasus pengidentifikasi dapat membingungkan pembaca. Contoh:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

Komentar di atas menyebutkan class dan argument , keduanya tidak ditemukan dalam kode. Komentar ini dapat ditulis ulang sebagai:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

KERING dan BASAH

Saat Anda menulis kode, Anda ingin mematuhi prinsip KERING (jangan ulangi sendiri) dan hindari BASAH (tulis semuanya dua kali).

Ini juga berlaku untuk komentar. Hindari menggunakan beberapa pernyataan untuk mendeskripsikan kode Anda, dan cobalah menggabungkan komentar yang menjelaskan kode yang sama menjadi satu komentar. Namun, penting untuk berhati-hati saat Anda menggabungkan komentar: penggabungan beberapa komentar yang tidak hati-hati dapat menghasilkan komentar besar yang melanggar panduan gaya dan sulit diikuti oleh pembaca.

Ingatlah bahwa komentar harus mengurangi waktu membaca kode.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

Dalam kode di atas, komentar tidak perlu terfragmentasi, dan dapat digabungkan menjadi satu komentar:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Lekukan yang Konsisten

Pastikan bahwa komentar diberi indentasi pada tingkat yang sama dengan kode yang dijelaskannya. Jika tidak, mereka bisa sulit untuk diikuti.

Misalnya, komentar ini tidak diindentasi atau diposisikan dengan benar:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Itu dapat ditulis ulang sebagai berikut:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

Ringkasan

Komentar adalah komponen penting dalam menulis kode yang dapat dimengerti. Investasi yang Anda lakukan dalam menulis komentar adalah salah satu yang akan dihargai oleh diri Anda di masa depan — atau pengembang lain yang perlu mengerjakan basis kode Anda. Mengomentari juga memungkinkan Anda untuk mendapatkan wawasan yang lebih dalam tentang kode Anda.

Dalam tutorial ini, Anda telah belajar lebih banyak tentang komentar di Python, termasuk berbagai jenis komentar Python, kapan menggunakan masing-masing komentar, dan praktik terbaik yang harus diikuti saat membuatnya.

Menulis komentar yang baik adalah keterampilan yang perlu dipelajari dan dikembangkan. Untuk berlatih menulis komentar, pertimbangkan untuk kembali dan menambahkan komentar ke beberapa proyek Anda sebelumnya. Untuk inspirasi dan melihat praktik terbaik dalam tindakan, lihat proyek Python yang terdokumentasi dengan baik di GitHub.

Ketika Anda siap untuk membuat proyek Python Anda sendiri hidup, platform Hosting Aplikasi Kinsta bisa mendapatkan kode Anda dari GitHub ke cloud dalam hitungan detik.