75 Mendokumentasikan Resolver dengan Komentar Go

Pernahkah Anda sebagai software engineer merasa frustasi ketika membaca kode lama tanpa dokumentasi yang memadai? Atau mungkin pernah code review di tim, dan menemukan resolver yang “ajaib” tanpa penjelasan sama sekali di baris komentarnya? Tahukah Anda bahwa dokumentasi yang baik tidak hanya membuat kode lebih mudah dipelihara, tapi juga sangat membantu pengembang lain memahami niat, logika, serta asumsi yang Anda buat ketika menulis kode—hingga mengurangi cost onboarding tim baru.

Pada artikel kali ini, saya ingin membahas pentingnya mendokumentasikan resolver dengan komentar idiomatik di Go (Golang). Kita akan bahas best practices, contoh kode, hingga simulasi kecil tentang dampak kode yang terdokumentasi. Di akhir artikel Anda juga akan menemukan table checklist dan contoh diagram alur menggunakan Mermaid untuk memperjelas dokumentasi.

Mengapa Fokus pada Resolver?

Resolver adalah bagian penting dalam beberapa arsitektur aplikasi, seperti pada GraphQL, dependency injection dalam domain-driven design, maupun proxy pada RPC. Resolver bertugas “resolve”—mengurai, menerjemahkan, dan menjembatani antara permintaan dan penyedia data atau layanan.

Karena sering menjadi titik entry sekaligus bridging logic, resolver kerap menampung logika kompleks. Jika tidak terdokumentasi, sering timbul masalah berikut:

• Ambiguity: Reviewer/kolega tidak memahami keputusan design.
• Debugging: Sulit menelusuri alur jika terjadi bugs.
• Regenerasi Spesifikasi: Dokumentasi otentik membantu regenerasi spesifikasi/api docs secara otomatis.

“Komentar Idiomatik”: Standar Dokumentasi di Go

Go punya filosofi “komentar bukan pengganti kode yang buruk”, namun justru memperkuat kode yang baik. Dokumentasi Go biasanya langsung di atas deklarasi fungsi, struct, ataupun interface, menggunakan komentar satu baris (//) yang ringkas namun informatif. Berkat tool seperti GoDoc, komentar ini dapat dirender ke dokumentasi HTML secara otomatis.

Pola Umum Dokumentasi Go:

// NameFunc mendeskripsikan apa yang dilakukan fungsi ini.
func NameFunc(args) ReturnType {...}

Studi Kasus: Resolver dalam Service Go

Bayangkan Anda membuat GraphQL API dengan resolver berikut:

func (r *queryResolver) User(ctx context.Context, id string) (*User, error) {
    user, err := r.userRepo.FindByID(ctx, id)
    if err != nil {
        return nil, err
    }
    return user, nil
}

Kode di atas tersirat mudah dibaca, tetapi adakah edge case yang harus diketahui developer lain? Bagaimana jika userRepo nil? Apa error yang mungkin dikembalikan?

Mari kita dokumentasikan fungsi ini secara idiomatik:

// User mengembalikan data User yang cocok dengan ID yang diberikan.
//
// Jika tidak ditemukan, akan mengembalikan error jenis ErrNotFound.
// Jika terjadi masalah internal pada repository, akan mengembalikan error terkait repository.
//
// Parameter:
//   - ctx: Context permintaan yang dikirim oleh klien, digunakan untuk tracing maupun cancelation.
//   - id: String unik sebagai identifier User.
//
// Return:
//   - *User: Objek User, jika ditemukan.
//   - error: Nil jika sukses, selain itu error detail masalah yang terjadi.
func (r *queryResolver) User(ctx context.Context, id string) (*User, error) {
    user, err := r.userRepo.FindByID(ctx, id)
    if err != nil {
        if errors.Is(err, repository.ErrNotFound) {
            return nil, fmt.Errorf("user %s not found: %w", id, err)
        }
        return nil, fmt.Errorf("failed to fetch user %s: %w", id, err)
    }
    return user, nil
}

Komentar di atas memperjelas:

• Deskripsi: Apa fungsi ini lakukan.
• Parameter: Penjelasan args, kadang dilengkapi tipe datanya.
• Return: Jelaskan return values.
• Error Handling: Kemungkinan error yang terjadi.

Simulasi: Kode dengan dan tanpa Komentar

1. Developer baru “onboarding” tanpa komentar

“Saya perlu mengubah cara fungsi User mengambil data user. Hm… oh, ternyata ini tergantung struct repo. Tapi, apa yang terjadi jika tidak ditemukan? Bagaimana format error-nya?”

2. Dengan komentar Go idiomatik

“Oke, ternyata error kembali sebagai ErrNotFound, jadi sudah ada handling-nya. Oh, dan repo ini bisa mengembalikan error internal juga.”

Waktu onboarding tim baru bisa berkurang 30-50% hanya karena dokumentasi yang jelas di resolver.

Mermaid Diagram: Alur Resolver

Untuk memperjelas dokumentasi, tambahkan diagram alur sederhana di README atau GoDoc. Berikut contoh memakai kode Mermaid:

flowchart TD
    A[Client Request] --> B[Resolver User]
    B -->|Success| C[Fetch by ID from Repo]
    C -->|User Found| D[Return *User, nil]
    C -->|User Not Found| E[Return nil, ErrNotFound]
    C -->|Internal Error| F[Return nil, RepoError]

Diagram seperti ini membantu developer memahami jalur eksekusi fungsi, terutama resolver yang melewati banyak kondisi.

Best Practice: Komentar Resolver di Go

Tabel Checklist Dokumentasi

Tips Menulis Komentar Resolver yang Efektif

1. Gunakan format GoDoc
   Selalu awali komentar dengan nama fungsi/struct (untuk parsing GoDoc).

   // User mengembalikan data User berdasarkan ID.
   

2. Tulis dalam Bahasa Indonesia/Bahasa Inggris konsisten
   Biasanya gunakan bahasa Inggris, kecuali semua tim memakai bahasa Indonesia.
3. Jelaskan edge case & precondition
   Apa asumsi yang diambil? Apakah context harus aktif? Apakah param nil bisa diterima?
4. Jangan copy-paste signature fungsi
   Fokus pada why, what, dan when, bukan cara menggunakan sintaksnya.
5. Referensikan error dari package lain
   Seringkali resolver mengembalikan error dari dependency. Sebutkan error itu agar memudahkan debugging.

Kesimpulan

Mendokumentasikan resolver dengan komentar idiomatik Go adalah salah satu investasi termurah namun berdampak besar pada maintainability kode. Dengan dokumentasi yang baik, terutama pada bagian resolver, engineer lain bisa cepat mengerti alur besar, mengurangi guessing game saat debugging, dan memperlancar proses onboarding. Kombinasikan komentar Go, tabel, dan diagram flow untuk membuat kode Anda self-documented.

Ingat:
“Kode bagus, bisa digunain. Kode dengan dokumentasi bagus, jadi warisan bagi tim Anda.” – Engineer bijak

Tantangan untuk Anda: Review salah satu resolver favorit Anda, lalu tambahkan komentar idiomatik Go sejernih mungkin. Share improvement-nya ke rekan tim — rasakan dampak positifnya!

Referensi:

• https://go.dev/doc/comment
• https://pkg.go.dev/golang.org/x/tools/cmd/godoc
• https://mermaid.js.org/