Menguasai Docblock: Rahasia di Balik IntelliSense dan Kode yang Lebih Rapi

Sebagai seorang programmer alias coder, kamu pasti tahu yang namanya IntelliSense, kan? Itu loh, fitur keren di code editor (seperti VS Code) yang ketika kamu mau memanggil suatu fungsi atau mengetik nama variabel, tiba-tiba muncul popup atau autocomplete yang menunjukkan detail, tipe data, dan dokumentasi dari fungsi tersebut.

Pernah gak sih kamu bertanya-tanya: Kenapa bisa muncul seperti itu? Dari mana infonya berasal?

Jawabannya—seringkali—adalah Docblock.

Di artikel kali ini, kita akan bedah apa itu Docblock, kenapa ini penting banget buat kesehatan kode kamu, dan kita lihat contoh langsungnya di TypeScript dan Python.

Apa itu Docblock?

Docblock (Documentation Block) adalah blok komentar dengan format khusus yang biasanya ditaruh tepat di atas deklarasi function, class, method, atau variabel. Berbeda dengan komentar biasa yang cuma buat dibaca manusia, Docblock didesain supaya bisa dibaca oleh mesin (tools).

Tools apa aja yang baca?

IDE (seperti VS Code): Untuk menampilkan tooltip IntelliSense yang membantu kita coding.
Documentation Generators: Untuk bikin website dokumentasi otomatis (kayak TypeDoc buat JS/TS atau Sphinx buat Python).
Linter: Buat ngecek apakah cara kita pakai fungsinya sudah benar atau belum.

TypeScript / JavaScript (JSDoc & TSDoc)

Di dunia JavaScript dan TypeScript, format standar yang dipakai adalah JSDoc (atau versi lebih ketatnya, TSDoc). Ciri khasnya dimulai dengan /** dan ditutup dengan */. Setiap baris di dalamnya biasanya diawali bintang *.

Sebelum Pakai Docblock

Coba lihat fungsi sederhana ini tanpa dokumentasi:

function hitungDiskon(harga: number, tipe: string) {
  if (tipe === 'VIP') {
    return harga * 0.8;
  }
  return harga * 0.95;
}

Pas kamu panggil fungsi ini di file lain, TypeScript cuma bakal bilang kalau harga itu number dan tipe itu string. Tapi dia nggak ngasih tahu nilai tipe apa aja yang boleh, atau logika diskonnya kayak gimana. Programmer lain harus baca isi fungsinya dulu baru paham. Ribet, kan?

Setelah Pakai Docblock

Sekarang, yuk kita kasih Docblock:

/**
 * Menghitung harga akhir setelah diskon berdasarkan tipe pelanggan.
 * 
 * @remarks
 * Fungsi ini mengasumsikan harga dalam Rupiah, tapi bisa bekerja dengan mata uang apa saja.
 * 
 * @param harga - Harga dasar barang. Tidak boleh negatif.
 * @param tipe - Tingkatan pelanggan. Bisa 'VIP' (diskon 20%) atau 'Reguler' (diskon 5%).
 * @returns Harga akhir yang sudah didiskon.
 * 
 * @example
 * ```ts
 * const total = hitungDiskon(100000, 'VIP'); 
 * console.log(total); // Output: 80000
 * ```
 */
function hitungDiskon(harga: number, tipe: 'VIP' | 'Reguler'): number {
  if (tipe === 'VIP') {
    return harga * 0.8;
  }
  return harga * 0.95;
}

Apa yang berubah?

Deskripsi: Pas kamu hover mouse ke hitungDiskon, sekarang muncul penjelasan singkatnya.
@param: Menjelaskan setiap parameter. Bahkan kita bisa kasih tahu kalau tipe ‘VIP’ itu dapet diskon 20%. Ini ngebantu banget tanpa harus buka codingannya.
@example: Ini favorit saya. Tooltip bakal nampilin contoh kode cara pakainya. Programmer lain tinggal contek aja!

Python (Docstrings)

Di Python, ini disebut Docstrings. Uniknya, di Python ini bukan komentar (yang pakai #), tapi string literal yang ditaruh di baris pertama dalam fungsi, kelas, atau modul. Tandanya pakai triple quotes """.

Sebelum Docstring

def koneksi_db(host, port, retry):
    # Implementasi disembunyikan
    pass

Setelah Docstring

Ada beberapa gaya penulisan di Python (Google, NumPy, reST). Ini contoh pakai Google Style yang populer dan rapi:

def koneksi_db(host: str, port: int, retry: bool = False) -> bool:
    """Membuka koneksi ke database server.

    Mencoba terhubung ke host dan port yang ditentukan. Jika koneksi
    gagal dan retry bernilai True, fungsi akan mencoba satu kali lagi.

    Args:
        host (str): Hostname atau alamat IP server database.
        port (int): Nomor port untuk koneksi.
        retry (bool): Jika True, akan mencoba koneksi ulang saat gagal. Default False.

    Returns:
        bool: True jika koneksi sukses, False jika gagal.

    Raises:
        ConnectionError: Jika jaringan tidak dapat dijangkau.
        
    Example:
        >>> sukses = koneksi_db('localhost', 5432)
        >>> print(sukses)
        True
    """
    # Implementasi...
    return True

Keuntungan di Python:

Docstring ini bisa diakses langsung saat program jalan pakai koneksi_db.__doc__.
Tools dokumentasi kayak Sphinx bisa otomatis bikin website dokumentasi cantik dari tulisan ini.
Tentu saja, Pylance di VS Code bakal nampilin ini dengan rapi banget.

Tips & Trik Menggunakan Docblock

Jangan Tulis yang Sudah Jelas:
```
// JANGAN GINI
/**
 * @param nama - Nama user
 */
function printNama(nama: string) {}
```
Kalau nama variabelnya sudah jelas, mending tulis konstrain atau detail lain (misal: “Nama harus sesuai KTP” atau “Maksimal 50 karakter”).
Wajib Update: Dokumentasi yang salah lebih bahaya daripada gak ada dokumentasi. Kalau kamu ubah nama parameter atau logika fungsinya, pastikan ubah docblock-nya juga.
Pakai Markdown: Kebanyakan IDE modern support Markdown di dalam docblock. Manfaatkan bold, code blocks, dan list biar enak dibaca.
Jelaskan “Kenapa”, Bukan Cuma “Apa”: Kode menjelaskan apa yang terjadi. Docblock adalah tempat yang tepat buat jelasin kenapa kamu milih algoritma itu, atau peringatan tentang edge case.

Kesimpulan

Docblock itu bukan sekadar hiasan atau “biar kelihatan profesional”. Itu adalah alat komunikasi. Docblock menjembatani kode yang kamu tulis hari ini dengan developer (atau bahkan diri kamu sendiri!) yang akan membacanya bulan depan.

Dengan menambahkan JSDoc atau Docstring yang rapi, kamu gak cuma kasih komentar di kode; kamu aktif meningkatkan Developer Experience (DX) buat siapa aja yang ngerjain proyek itu.

Jadi, lain kali kamu bikin fungsi, luangkan waktu satu menit buat ketik /** atau """. Diri kamu di masa depan bakal berterima kasih!