Komentar dan gofmt

Topik ini membahas dua kebiasaan yang menyertai kode Go di mana pun ia ditulis, yaitu penulisan komentar dokumentasi dan pemakaian alat gofmt untuk menyeragamkan tata letak. Keduanya bukan pilihan gaya pribadi, melainkan budaya yang ditegakkan alat, karena seluruh kode Go di pustaka standar dan hampir seluruh proyek publik diformat dengan alat yang sama. Setelah membaca topik ini, komentar dapat ditulis mengikuti konvensi yang dibaca go doc, dan pemformatan berkas dapat diperiksa serta diperbaiki dengan perintah yang tepat.

Dua bentuk komentar#

Go mengenal dua bentuk komentar. Komentar baris diawali // dan berlaku sampai ujung baris, sedangkan komentar blok diapit /* dan */ dan dapat melintasi beberapa baris. Komentar baris adalah bentuk bawaan yang dipakai hampir di semua tempat, sedangkan komentar blok lazim dipakai untuk menonaktifkan kode secara sementara atau menyisipkan catatan di tengah baris. Di luar itu, komentar juga berfungsi sebagai dokumentasi, dan bentuk serta posisinya menentukan apakah alat dokumentasi dapat membacanya.

Komentar yang baik menambah informasi yang tidak tampak dari kode, misalnya alasan sebuah keputusan, batas masukan yang diharapkan, atau peringatan tentang perilaku yang tidak lazim. Komentar yang hanya mengulang isi barisnya, misalnya // tambah satu di atas i++, justru menambah beban baca tanpa nilai apa pun. Pedoman praktisnya, tulis komentar seolah pembacanya menguasai bahasa Go, tetapi tidak mengetahui maksud penulisnya.

Komentar dokumentasi#

Komentar yang berada tepat di atas deklarasi package, tipe, atau fungsi dibaca oleh alat go doc sebagai komentar dokumentasi. Konvensinya ketat dan sederhana, yaitu komentar fungsi dimulai dengan nama fungsi itu sendiri, dan kalimatnya menyatakan perilaku, bukan langkah implementasi. Berkas berikut memuat komentar dokumentasi pada tingkat package dan pada fungsi:

// Program konversi satuan waktu sederhana.
// Paket ini mendemonstrasikan penulisan komentar dokumentasi.
package main

import "fmt"

// menitKeJam mengonversi jumlah menit menjadi jam.
// Bagian menit yang tersisa dikembalikan sebagai nilai kedua.
func menitKeJam(totalMenit int) (jam int, sisaMenit int) {
	jam = totalMenit / 60
	sisaMenit = totalMenit % 60
	return jam, sisaMenit
}

func main() {
	jam, sisa := menitKeJam(135)
	fmt.Println("135 menit sama dengan", jam, "jam", sisa, "menit")
}

135 menit sama dengan 2 jam 15 menit

Komentar pada menitKeJam mengikuti pola baku, yaitu kalimat pertama diawali nama fungsi dan menjelaskan tugasnya dalam satu baris, lalu kalimat berikutnya melengkapi rinciannya. Pola ini bukan kebiasaan kosong, karena go doc dan pkg.go.dev menyajikan komentar itu apa adanya sebagai deskripsi fungsi. Contoh berikut menampilkan dokumentasi fmt.Println, yang teksnya persis berasal dari komentar dokumentasi di kode sumber pustaka standar:

go doc fmt.Println

package fmt // import "fmt"

func Println(a ...any) (n int, err error)
    Println formats using the default formats for its operands and writes to
    standard output. Spaces are always added between operands and a newline
    is appended. It returns the number of bytes written and any write error
    encountered.

Kalimat deskripsi di atas, yang diawali nama fungsi dan menyebut perilaku spasi serta baris baru, adalah komentar dokumentasi yang telah dibaca ulang oleh alat. Menulis komentar dengan pola yang sama berarti berkontribusi pada dokumentasi sejak baris pertama, tanpa berkas terpisah.

gofmt: satu format untuk semua#

gofmt adalah alat resmi yang memformat kode Go menurut satu aturan tunggal, mencakup indentasi, spasi di sekitar operator, penempatan kurung kurawal, dan pengelompokan impor. Aturan itu diatur sedemikian rupa sehingga tidak ada ruang perdebatan gaya, dan keseragamannya membuat kode siapa pun terbaca seperti kode pustaka standar. Alat ini menyertai instalasi Go, sehingga tidak ada langkah tambahan untuk memakainya.

gofmt tidak menyediakan pilihan gaya, dan ketiadaan konfigurasi itu memang tujuan utamanya. Seluruh kode pustaka standar Go diformat dengan alat ini sejak rilis awal, sehingga pembaca kode mana pun tidak perlu menyesuaikan diri dengan kebiasaan penulisnya. Manfaat lain muncul pada tinjauan kode, karena seluruh perbedaan baris pada perubahan berupa substansi, bukan spasi dan indentasi.

Efeknya paling mudah diamati pada berkas yang sengaja ditulis buruk. Berkas buruk.go berikut tetap sah sebagai program, tetapi tata letaknya melanggar aturan gofmt di beberapa tempat:

package main
import "fmt"
func main() {
suhu:=24
fmt.Println("Suhu",suhu,"derajat Celsius")
}

Suhu 24 derajat Celsius

Program yang berantakan tetap berjalan benar, karena makna kode tidak bergantung pada tata letaknya. Meski demikian, berkas semacam ini gagal pemeriksaan format, dan itulah yang dideteksi langkah berikut.

Memeriksa dan memperbaiki dengan gofmt#

Bendera -l menyenaraikan berkas yang tata letaknya belum sesuai, tanpa mengubah apa pun. Urutan berikut menyiapkan folder latihan tetap, menyalin kedua berkas contoh, lalu memeriksa seluruh folder:

mkdir -p /tmp/gofmt-demo
cp buruk.go rapi.go /tmp/gofmt-demo/
cd /tmp/gofmt-demo
gofmt -l .

buruk.go

Hanya buruk.go yang tersenarai, sedangkan rapi.go lolos karena sudah mengikuti aturan. Bendera -d menampilkan perbedaan antara isi berkas dan versi terformat dalam bentuk diff, yaitu tampilan perubahan berstandar Unix, tanpa mengubah berkasnya. Baris bertanda - dihapus dan baris bertanda + menggantikannya:

gofmt -d buruk.go

diff buruk.go.orig buruk.go
--- buruk.go.orig
+++ buruk.go
@@ -1,6 +1,8 @@
 package main
+
 import "fmt"
+
 func main() {
-suhu:=24
-fmt.Println("Suhu",suhu,"derajat Celsius")
+	suhu := 24
+	fmt.Println("Suhu", suhu, "derajat Celsius")
 }

Perbedaannya tampak pada tiga hal, yaitu baris kosong pemisah setelah klausa package dan impor, spasi di sekitar operator := dan koma, serta indentasi badan fungsi dengan satu tab. Perbaikan seluruhnya dilakukan dengan bendera -w, yang menulis ulang berkas dalam format yang benar, dan pemeriksaan ulang sesudahnya tidak tersenarai apa pun:

gofmt -w buruk.go
gofmt buruk.go

package main

import "fmt"

func main() {
	suhu := 24
	fmt.Println("Suhu", suhu, "derajat Celsius")
}

Tanpa bendera apa pun, gofmt mencetak versi terformat ke layar, sehingga berguna untuk mengintip hasil tanpa menyentuh berkas. Alat go vet yang memeriksa pola kode mencurigakan melengkapi alur kerja ini, tetapi gofmt tetap alat pertama yang dijalankan sebelum kode dibagikan.

Ringkasan#

• Komentar baris // adalah bentuk bawaan, dan komentar tepat di atas deklarasi menjadi dokumentasi yang dibaca go doc.
• Komentar dokumentasi fungsi diawali nama fungsinya dan menyatakan perilaku, sebagaimana tampak pada keluaran go doc fmt.Println.
• gofmt menyeragamkan tata letak kode dengan satu aturan, sehingga kode proyek apa pun terbaca dengan pola yang sama.
• gofmt -l . menyenaraikan berkas yang belum terformat, -d menampilkan perbedaannya, dan -w menulis ulang berkasnya.

Referensi#

• The Go Blog: go fmt your code — The Go Blog — Artikel resmi yang menjelaskan alasan pemformatan kode ditegakkan satu aturan.
• Effective Go: Commentary — Go Documentation — Konvensi resmi komentar dokumentasi dan kaitannya dengan godoc.
• Go Doc Comments — Go Documentation — Rujukan resmi bentuk komentar dokumentasi yang dibaca alat go doc.