BAB 5: Comment — Menulis Catatan dalam Kode

Program main.go yang kamu tulis di bab sebelumnya sudah bisa dijalankan dan dipahami sekarang — karena kodenya pendek. Tapi bayangkan enam bulan dari sekarang, kamu membuka file yang berisi ratusan baris logika bisnis. Tanpa penjelasan tambahan, kamu akan kesulitan mengingat kenapa kode tertentu ditulis seperti itu. Comment adalah jawabannya.

Comment bukan hiasan. Dalam tim, comment adalah cara berkomunikasi dengan programmer lain. Saat sendirian, comment adalah pesan untuk diri kamu di masa depan. Go juga punya alasan tambahan untuk serius soal comment: tool bawaan seperti go doc bisa mengubah comment menjadi dokumentasi yang bisa dibaca langsung dari terminal.

Dua Jenis Comment

Go hanya mengenal dua sintaks comment, dan keduanya sudah lebih dari cukup.

Single-line comment

Dimulai dengan //, berlaku sampai akhir baris. Ini yang paling sering dipakai:

// main.go
package main

import "fmt"

func main() {
    // Mencetak salam ke terminal
    fmt.Println("Hello, Go!")

    nama := "Gopher" // nama bisa diganti sesuai kebutuhan
    fmt.Println("Halo,", nama)
}

Comment bisa berdiri sendiri di baris terpisah, atau diletakkan di akhir baris kode. Keduanya valid — pilih yang paling mudah dibaca dalam konteks tersebut.

Multi-line comment

Dimulai dengan /* dan ditutup dengan */. Dipakai ketika penjelasan butuh lebih dari satu baris, atau ketika kamu ingin menonaktifkan blok kode sementara:

/*
calculateTax menghitung pajak penghasilan.
Rumus: income * rate
Rate diterima dalam bentuk desimal: 0.15 untuk 15%.
*/
func calculateTax(income, rate float64) float64 {
    return income * rate
}

Documentation Comment

Go punya konvensi khusus yang membuat comment bukan sekadar teks biasa: documentation comment. Comment yang diletakkan tepat sebelum deklarasi func, type, var, atau const — tanpa baris kosong di antaranya — akan terbaca oleh go doc sebagai dokumentasi resmi.

Konvensi Go mengharuskan documentation comment dimulai dengan nama yang didokumentasikan:

// main.go
package main

import "fmt"

// greet mencetak salam ke terminal dengan nama yang diberikan.
func greet(name string) {
    fmt.Printf("Halo, %s!\n", name)
}

// add menjumlahkan dua bilangan dan mengembalikan hasilnya.
func add(a, b int) int {
    return a + b
}

func main() {
    greet("Gopher")
    fmt.Println(add(3, 7))
}

Untuk melihat documentation comment yang kamu tulis, jalankan:

go doc .

Atau untuk function tertentu:

go doc main.greet

Ini terlihat seperti detail kecil sekarang, tapi ketika project kamu punya banyak function dan package, kemampuan membaca dokumentasi langsung dari terminal sangat menghemat waktu.

Comment yang Baik vs Buruk

Tidak semua comment membantu. Comment yang buruk malah menjadi noise — menambah teks tanpa menambah pemahaman.

Comment yang hanya mengulangi apa yang sudah jelas dari kode adalah contoh yang buruk:

// Bad: mengulang kode, tidak menambah informasi
x := 5        // set x to 5
x = x + 1     // add 1 to x
fmt.Println(x) // print x

Comment yang baik menjelaskan kenapa — alasan di balik keputusan yang tidak terlihat dari kode itu sendiri:

// Rate disimpan sebagai desimal karena berasal dari API eksternal
// yang mengembalikan nilai dalam rentang 0.0–1.0, bukan 0–100
rate := fetchTaxRate()

// Tambah buffer 10% untuk antisipasi fluktuasi harga bahan baku
estimatedCost := baseCost * 1.1

Prinsipnya sederhana: jelaskan kenapa, bukan apa. Kode sendiri sudah menunjukkan apa yang dilakukan.

Anotasi TODO dan FIXME

Ada dua anotasi yang secara konvensi dipakai di seluruh ekosistem Go (dan hampir semua bahasa lain):

func processOrder(orderID string) {
    // TODO: tambahkan validasi format orderID sebelum diproses
    // FIXME: jika orderID kosong, fungsi ini akan panic — perlu guard clause

    fmt.Println("Processing order:", orderID)
}

TODO menandai pekerjaan yang belum selesai tapi disengaja ditunda. FIXME menandai bug yang diketahui dan perlu segera diperbaiki. Banyak editor dan CI tool bisa mencari anotasi ini secara otomatis, membuatnya lebih mudah dilacak.

Latihan

1. Ambil kode main.go yang sudah kamu buat di bab sebelumnya. Tambahkan documentation comment di atas func main() yang menjelaskan apa yang dilakukan program tersebut. Jalankan go doc . dan perhatikan hasilnya.

2. Tulis sebuah function bernama multiply yang mengalikan dua integer dan mengembalikan hasilnya. Tambahkan documentation comment yang mengikuti konvensi Go — dimulai dengan nama function.

3. Coba tulis dua versi comment untuk baris kode yang sama: satu yang buruk (mengulangi kode) dan satu yang baik (menjelaskan alasan). Ini membantu melatih instinct dalam membedakan keduanya.

Comment adalah kebiasaan yang terbentuk perlahan. Kamu tidak perlu meng-comment setiap baris — cukup bagian yang logikanya tidak langsung terlihat. Seiring kode bertambah kompleks, kamu akan semakin merasakan nilainya.

Sejauh ini program kita hanya bekerja dengan nilai yang langsung ditulis di kode. Tidak ada cara untuk menyimpan dan mengubah data selama program berjalan. Di bab berikutnya kita akan memperkenalkan variabel — mekanisme Go untuk menyimpan, mengubah, dan meneruskan data dari satu bagian program ke bagian lainnya.