Komen dan Docstring dalam Python

Comment and Docstring in Python

ยท

3 min read

Pengenalan

Hai semua! Kembali lagi dalam Python dalam Melayu. Artikel hari ini kita akan membincangkan perkara yang mudah sahaja, tetapi sangat berguna semasa kita menulis kod dalam Python! ๐Ÿ˜

Apa yang kita akan bincangkan hari ini adalah berkenaan komen dan docstring! Ayuh kita dalami dengan lebih lanjut kepada kedua-dua perkara ini. ๐Ÿ˜Ž

Komen

Semasa menulis kod, adakalanya kita ingin meletakkan nota kecil/peringatan pada kod yang telah kita tulis supaya dapat dirujuk oleh kita atau rakan-rakan kita pada masa akan datang. Tetapi, kita tidak bolehlah sembarangan menulis sesuatu di dalam skrip Python, kerana Python (dan bahasa pengaturcaraan lain) mempunyai disiplin yang tersendiri dalam menulis kod.

Contoh, anda ingin meletakkan nota bahawa pemboleh ubah x menyimpan nama rakan anda. Jadi anda terus menulisnya seperti kod dibawah,

nama rakan-rakan
x = "Abu"

print(x)

Output:

  File "<ipython-input-1-169f776a8317>", line 1
    nama rakan-rakan
             ^
SyntaxError: invalid syntax

Python akan mengeluarkan ralat kerana tidak dapat mengenalpasti apakah yang sebenarnya yang anda ingin maksudkan.

Jadi, bagaimana kita boleh meletakkan nota rujukan di dalam kod kita, tanpa mempengaruhi bacaan kod dalam Python?

Jawapannya, kita boleh gunakan awalan tanda pagar, # untuk menyatakan bahawa perkataan selepas tanda pagar ini adalah komen, bukan kod untuk dibaca Python.

Komen adalah sebuah string yang akan diabaikan oleh Python bagi tujuan kegunaan pengaturcara meletakkan nota dalam kod.

Jadi untuk memperbetulkan kod di atas, cuma tambahkan tanda pagar pada awalan nama rakan-rakan kepada #nama rakan-rakan.

#nama rakan-rakan
x = "Abu"

print(x)

Output:
Abu

#nama rakan-rakan sekarang dikenali sebagai komen. Komen boleh digunakan dimana-mana sahaja di dalam Python, asalkan berada di luar kod. Komen akan diabaikan oleh Python dan tidak akan memberi apa-apa pengaruh kepada program.

Selain daripada menggunakan tanda pagar, kita juga boleh gunakan 3 pembuka dan penutup kata jika komen tersebut mempunyai beberapa baris. Contoh;

'''
Nota ini ditulis pada 
Hari : Isnin
Masa : 3:45 petang
'''
'''Boleh juga digunakan dalam satu barisan.'''
x = "Ali"
print(x)

Output:
Ali

Sama juga seperti tanda pagar, kesemua string yang berada di dalam 3 pembuka dan penutup kata akan diabaikan oleh program dan dianggap sebagai komen. Namun, penggunaan 3 pembuka dan penutup kata ini juga boleh digunakan bagi tujuan lain iaitu, docstring.

Apa itu docstring? Mari kita pergi ke tajuk seterusnya.

Docstring

Docstring adalah sebuah string yang muncul sebagai nota/dokumentasi sesebuah fungsi definisi, class, metod, atau modul.

Docstring telah terbina dalam modul bagi kemudahan pengaturcara untuk mengetahui kegunaan modul tersebut.

Sebagai contoh, jika anda ingin membaca penerangan sesuatu modul, anda boleh menulis .__doc__ dimana merujuk kepada atribut docstring kepada modul tersebut.

import math

print(math.__doc__)

Output:
This module provides access to the mathematical functions
defined by the C standard.

Kita juga boleh mencipta docstring sendiri. Penggunaannya adalah sama sahaja dengan penggunaan komen yang mempunyai beberapa baris iaitu dengan menggunakan 3 pembuka dan penutup kata. Apa yang membezakannya adalah, docsstring akan berada di bawah/dalam fungsi definisi, class ataupun metod.

Contoh:

def calculate_this(a, b):
    '''
    This definition is use to calculate 2 values, a and b
    '''
    return a + b

print("Answer:", calculate_this(1,2))
print(calculate_this.__doc__)

Output:
Answer: 3

    This definition is use to calculate 2 values, a and b

Berdasarkan fungsi definisi di atas, anda dapat lihat bahawa terdapat docstring dibawahnya yang menerangkan kegunaan fungsi tersebut. Anda boleh mengoutput dosctring tersebut dengan cara print(<function>.__doc__).

hash1.png

Dan jika anda meletakkan cursor anda ke atas fungsi tersebut, terdapat satu kotak dialog yang akan menerangkan kegunaan fungsi anda berdasarkan apa yang anda telah tulis dalam docstring.

Docstring hanya akan menjadi docstring jika anda menulis string ini di dalam fungsi, metod atau class. Jika tidak, ianya akan dianggap sebagai komen biasa.

Penutup

Komen dan docstring dapat membantu pengaturcara untuk memahami semula kod dengan meletakkan nota kecil pada kod yang ditulis supaya dapat dirujuk oleh kita (jika terlupa) dan dapat difahami oleh orang lain yang membaca kod kita.

Sampai disitu sahaja perkongsian kali ini. Harap anda dapat memanfaatkan ilmu pengetahuan yang telah disampaikan dalam artikel ini.

Sampai jumpa, salam! ๐Ÿ‘‹

ย