Penamaan, komentar & API yang enak dipakai

Go punya sedikit sekali aturan gaya, tapi yang sedikit itu dipatuhi hampir universal. Mengikutinya membuat kodemu terbaca oleh orang yang belum pernah melihat repomu.

Panjang nama sebanding dengan jaraknya

// Pendek — hidupnya tiga baris, konteksnya jelas
for i, p := range daftar {
	if p.Harga > batas {
		hasil = append(hasil, p)
	}
}

// Panjang — diekspor, dibaca orang yang tidak melihat isinya
func HitungOngkirBerdasarkanZona(ctx context.Context, tujuan Alamat) (Rupiah, error)

Ini kebalikan dari kebiasaan di beberapa bahasa lain, di mana nama panjang dianggap selalu lebih baik. Di Go, i di dalam loop tiga baris lebih jelas daripada indeksProdukSaatIni, karena pembaca bisa melihat seluruh hidupnya dalam satu pandangan.

Konteks paket sudah jadi awalan

Yang dibaca di tempat pemakaian adalah paket.Nama secara utuh, jadi rancanglah kalimat itu. bytes.Buffer, time.Now, slices.Sort — semuanya terbaca sebagai frasa.

Singkatan tidak pernah dipecah

userID     ID      URL      HTTPServer     apiKey    XMLData
// bukan:
userId     Id      Url      HttpServer     ApiKey    XmlData

Aturannya: singkatan ditulis konsisten seluruhnya besar atau seluruhnya kecil, tergantung apakah nama itu diekspor. xmlData (privat) dan XMLData (publik), tidak pernah XmlData. Linter revive dan staticcheck menegakkannya (Fase 8).

Komentar dokumentasi

// Package produk berisi model dan aturan bisnis katalog produk.
//
// Paket ini tidak tahu apa pun tentang HTTP maupun database; penyimpanan
// diakses lewat interface yang dideklarasikan di sini.
package produk

// ErrTidakDitemukan dikembalikan saat produk yang diminta tidak ada.
// Lapisan HTTP memetakannya jadi 404.
var ErrTidakDitemukan = errors.New("produk tidak ditemukan")

// Cari mengembalikan produk yang namanya mengandung kata, diurutkan dari
// yang paling murah. Ia mengembalikan slice kosong (bukan error) kalau tidak
// ada yang cocok.
//
// Kata dibandingkan tanpa memperhatikan huruf besar-kecil.
func Cari(ctx context.Context, kata string) ([]Produk, error) {

go doc ./internal/produk          # baca dokumentasi paketmu sendiri
go doc ./internal/produk Cari     # satu simbol
go doc -http=:6060                # jelajahi seluruh modul di browser

Nama interface dan konstruktor

// Satu method: kata kerja + -er
type Reader interface   { Read(...) }
type Penyimpan interface { Simpan(...) }

// Beberapa method: nama peran, bukan -er yang dipaksakan
type PenyimpanProduk interface {
	Ambil(ctx context.Context, id int64) (Produk, error)
	Simpan(ctx context.Context, p Produk) error
}

// Konstruktor
func New(...) *Layanan          // kalau paketnya cuma punya satu tipe utama
func NewLayanan(...) *Layanan   // kalau ada beberapa

Yang membuat API enak dipakai

1. ctx context.Context selalu parameter pertama, dan tidak pernah disimpan di dalam struct.
2. error selalu nilai kembalian terakhir.
3. Nilai nol yang berguna — kalau tipemu perlu konstruktor, itu keputusan sadar.
4. Terima interface, kembalikan struct.
5. Jangan kembalikan nilai kembalian tak bernama yang lebih dari dua — tiga nilai anonim adalah tanda struct hasil dibutuhkan.
6. Fungsi yang bisa gagal harus mengembalikan error, bukan mencatat log lalu diam.