Komentar #

Pengertian #

Komentar dalam bahasa pemrograman adalah teks yang ditulis dalam kode sumber suatu program tetapi tidak dieksekusi atau diproses oleh komputer. Komentar digunakan untuk memberikan penjelasan, catatan, atau dokumentasi tambahan yang dapat membantu programmer lain (atau diri sendiri di masa depan) untuk memahami logika atau tujuan dari kode tersebut. Komentar juga dapat digunakan untuk menonaktifkan bagian dari kode selama pengembangan atau debugging.

Kegunaan Komentar #

• Menjelaskan kode: Komentar membantu programmer lain (atau diri sendiri di masa depan) memahami apa yang dilakukan oleh bagian tertentu dari kode.
• Mendokumentasikan kode: Komentar sering digunakan untuk memberikan informasi tentang fungsi, kelas, atau modul tertentu.
• Menonaktifkan kode: Kadang-kadang, programmer ingin menonaktifkan bagian dari kode tanpa menghapusnya. Dengan menambahkan # di depan baris, baris tersebut tidak akan dieksekusi.

Jenis Komentar #

Di Python, komentar digunakan untuk menjelaskan kode dan membantu pembaca memahami maksud dari suatu bagian program. Komentar tidak dieksekusi oleh interpreter Python. Ada dua jenis utama komentar di Python:

Baris Tunggal #

• Komentar ini dimulai dengan simbol #. Semua teks setelah simbol ini pada baris yang sama akan diabaikan oleh interpreter.

• Contoh:

  # Ini adalah komentar baris tunggal
  print("Hello, World!")  # Mencetak pesan ke layar
      ```
  

Beberapa Baris #

• Python tidak memiliki sintaks komentar beberapa baris secara langsung seperti beberapa bahasa lain, tetapi kita bisa menggunakan string tiga tanda kutip (''' atau """). Jika string ini tidak digunakan sebagai nilai, maka dapat berfungsi sebagai komentar.

• Contoh:

  """
  Ini adalah komentar beberapa baris.
  Komentar ini bisa menjelaskan
  beberapa hal sekaligus.
  """
  print("Hello, World!")
  

Docstring #

Docstring (documentation string) di Python adalah jenis komentar khusus yang digunakan untuk mendokumentasikan fungsi, kelas, metode, atau modul. Docstring memberikan informasi tentang apa yang dilakukan oleh suatu komponen dan bagaimana cara menggunakannya.

Cara Menulis #

Docstring ditulis dengan menggunakan tanda kutip tiga (''' atau """). Ini bisa ditulis pada baris pertama di dalam fungsi, kelas, atau modul.

Contoh Penggunaan #

Docstring untuk Fungsi #

def tambah(a, b):
    """
    Mengembalikan jumlah dari dua angka.

    Args:
        a (int, float): Angka pertama.
        b (int, float): Angka kedua.

    Returns:
        int, float: Jumlah dari a dan b.
    """
    return a + b

Docstring untuk Kelas #

class Mobil:
    """
    Kelas yang merepresentasikan sebuah mobil.

    Attributes:
        merek (str): Merek mobil.
        model (str): Model mobil.
    """

    def __init__(self, merek, model):
        self.merek = merek
        self.model = model

Docstring untuk Modul #

"""
Modul ini menyediakan fungsi untuk melakukan operasi matematika dasar.
"""

def kali(a, b):
    return a * b

Kegunaan #

• Dokumentasi: Docstring memungkinkan programmer untuk mendokumentasikan kode secara langsung di dalamnya, sehingga memudahkan orang lain (atau diri sendiri di masa depan) untuk memahami fungsi atau kelas yang ditulis.
• Akses melalui help(): Docstring dapat diakses menggunakan fungsi help(), sehingga dapat memberikan informasi yang berguna tanpa harus melihat kode sumber.
• IDE dan Alat Pembantu: Banyak Integrated Development Environment (IDE) dan alat dokumentasi otomatis yang menggunakan docstring untuk menghasilkan dokumentasi yang jelas dan terstruktur.

Format #

Meskipun tidak ada aturan baku, ada beberapa format umum yang sering digunakan dalam penulisan docstring, antara lain:

Google Style #

def function(arg1, arg2):
    """
    Deskripsi singkat tentang fungsi.

    Args:
        arg1 (int): Deskripsi arg1.
        arg2 (str): Deskripsi arg2.

    Returns:
        bool: Deskripsi tentang nilai yang dikembalikan.
    """

NumPy/SciPy Style #

def function(arg1, arg2):
    """
    Deskripsi singkat tentang fungsi.

    Parameters
    ----------
    arg1 : int
        Deskripsi arg1.
    arg2 : str
        Deskripsi arg2.

    Returns
    -------
    bool
        Deskripsi tentang nilai yang dikembalikan.
    """

reStructuredText (reST) #

Digunakan dalam banyak proyek Python, termasuk Sphinx untuk menghasilkan dokumentasi.

Tips Menulis Komentar #

• Buat komentar yang jelas dan singkat.
• Hindari komentar yang berlebihan atau tidak perlu. Cukup tambahkan komentar di tempat yang memang perlu penjelasan tambahan.
• Gunakan komentar untuk menjelaskan “mengapa” bukan hanya “apa”. Ini membantu memberikan konteks yang lebih baik kepada pembaca.

Kesimpulan #

Dengan menggunakan komentar secara efektif, kode Python menjadi lebih mudah dipahami dan dikelola.