Ketika Anda berpikir tentang pemrograman, wajar untuk fokus pada topik seperti bahasa, algoritme, dan debugging. Tapi dokumentasi teknis bisa sama pentingnya untuk mendapatkan yang benar.
Tanpa dokumentasi yang baik, penggunaan kembali kode dapat terganggu. Pengguna yang baru mengenal basis kode dapat dengan mudah tersesat atau frustrasi jika dokumentasi tidak sesuai standar. Tidak hanya penting untuk memahami apa yang dilakukan suatu program, tetapi bagaimana—atau bahkan mengapa—ia melakukannya.
Paket seperti Pydoc untuk Python dan Javadoc untuk Java membantu dengan mengotomatiskan sebagian proses. Alat Godoc melakukan hal yang sama untuk Go.
Apa Itu Godok?
Godoc adalah paket Go yang memungkinkan Anda membuat, mengelola, dan menggunakan dokumentasi Go dalam "cara Go". Cara Go adalah seperangkat prinsip yang, sebagai programmer Go, harus Anda ikuti untuk meningkatkan kualitas kode.
Menggunakan Godoc, Anda dapat dengan mudah membaca dokumentasi dan kode pengembang lain. Anda juga dapat mengotomatiskan pembuatan dokumentasi Anda sendiri dan mempublikasikannya menggunakan Godoc.
Godoc mirip dengan Javadoc, dokumenter kode untuk Java. Keduanya menggunakan komentar dan kode dalam modul untuk menghasilkan dokumentasi. Dan kedua alat tersebut menyusun dokumentasi itu dalam HTML sehingga Anda dapat melihatnya di browser.
Memulai Dengan Godoc
Menggunakan Godoc itu mudah. Untuk memulai, instal paket Godoc dari situs web golang menggunakan perintah ini:
Pergilah dapatkan golang.org/x/tools/cmd/godoc
Menjalankan perintah ini akan menginstal Godoc di ruang kerja yang Anda tentukan. Setelah selesai, Anda harus dapat menjalankan godoc perintah di terminal. Jika ada kesalahan dengan penginstalan Anda, coba perbarui Go ke versi terbaru.
Godoc mencari komentar baris tunggal dan ganda untuk disertakan dalam dokumentasi yang dihasilkannya.
Pastikan untuk memformat kode dengan cara Go, seperti yang dijelaskan di publikasi Go yang Efektif oleh tim Go untuk hasil terbaik.
Berikut ini contoh penggunaan komentar satu baris bergaya C++:
// Pengguna adalah model struct yang berisi
Tipe Pengguna struktur {
}
Anda juga dapat menggunakan komentar blok gaya-C:
/*
Pengguna adalah struktur data khususAnda dapat memasukkan teks apa pun di sini dan server Godoc akan memformatnya saat Anda menjalankannya.
*/
Tipe Pengguna struktur {
}
Dalam komentar di atas, "Pengguna" memulai kalimat karena komentar tersebut menjelaskan apa yang dilakukan oleh struktur Pengguna. Ini adalah salah satu dari banyak topik yang dibahas dengan cara Go. Memulai kalimat dokumentasi dengan nama yang berguna sangat penting karena kalimat pertama muncul dalam daftar paket.
Menjalankan Server Godoc
Setelah Anda mengomentari kode Anda, Anda dapat menjalankan godoc perintah di terminal Anda, dari direktori kode proyek Anda.
Secara konvensional, pengembang Go menggunakan port 6060 untuk menjadi tuan rumah dokumentasi. Ini adalah perintah untuk menjalankan server Godoc di port itu:
godoc -http=:6060
Perintah di atas menghosting dokumentasi kode Anda di localhost, atau 127.0.0.1. Port tidak harus 6060; godoc akan berjalan di semua port yang tidak terisi. Namun, yang terbaik adalah selalu mengikuti konvensi dokumentasi Go.
Setelah Anda menjalankan perintah, Anda dapat melihat dokumentasi Anda di browser dengan mengunjungi host lokal: 6060. Waktu yang dibutuhkan Godoc untuk membuat dokumentasi Anda akan bergantung pada ukuran dan kerumitannya.
Kode di bawah ini menganut cara Go, dalam hal ini menggunakan komentar satu baris.
// nama paket
kemasan pengguna// fmt bertanggung jawab untuk memformat
impor (
"fmt"
)// Pengguna adalah struktur data manusia
Tipe Pengguna struktur {
Usia ke dalam
Nama rangkaian
}fungsiutama() {
// manusia adalah inisialisasi dari struktur Pengguna
manusia := Pengguna {
Usia: 0,
Nama: "orang",
}fmt. Println (manusia. Bicara())
}
// Bicara adalah metode dari struct Pengguna
fungsi(Pengguna penerima)Bicara()rangkaian {
kembali "Setiap Pengguna Dapat Mengatakan Sesuatu!"
}
Jika Anda menjalankan Godoc pada modul kode di atas, Anda akan melihat output seperti ini:
Perhatikan bahwa itu dalam format yang familier, mirip dengan apa yang akan Anda temukan di situs web dokumentasi resmi Go.
Godoc menggunakan komentar sebelum deklarasi paket sebagai Ringkasan. Pastikan komentar ini menjelaskan apa yang dilakukan program Anda.
Itu Indeks berisi tautan ke deklarasi tipe dan metode sehingga Anda dapat menavigasinya dengan cepat.
Godoc juga menyediakan fungsionalitas untuk melihat kode sumber yang menyusun paket di File paket bagian.
Meningkatkan Dokumentasi Anda Menggunakan Godoc
Anda dapat memasukkan lebih dari sekadar teks biasa dalam dokumentasi Godoc Anda. Anda dapat menambahkan URL yang akan dibuatkan tautan oleh Godoc dan menyusun komentar Anda ke dalam paragraf.
Jika Anda ingin menautkan ke sumber daya, tulis URL di komentar Anda, dan Godoc akan mengenalinya dan menambahkan tautan. Untuk paragraf, tinggalkan baris komentar kosong.
// Paket utama
kemasan utama// Dokumen mewakili dokumen biasa.
//
// Tautkan ke https://google.com
Tipe Dokumen struktur {
halaman ke dalam
referensi rangkaian
tertanda bool
}// Tulis menulis Dokumen baru ke penyimpanan
//
// Anda dapat belajar tentang menulis dari Wikipedia.com
fungsiMenulis() {
}
Perhatikan bahwa Godoc mengharuskan Anda untuk menulis URL secara lengkap agar dapat menautkannya. Dalam contoh ini, URL Google menyertakan https:// awalan, jadi Godoc menambahkan tautan ke sana. Karena domain Wikipedia bukan URL lengkapnya sendiri, Godoc akan membiarkannya sendiri.
Berikut adalah beberapa prinsip terbaik untuk diterapkan saat mendokumentasikan kode Go Anda:
- Buat dokumentasi Anda tetap sederhana dan ringkas.
- Mulailah kalimat fungsi, tipe, dan deklarasi variabel dengan namanya.
- Mulai baris dengan indentasi untuk memformatnya terlebih dahulu sebagai kode.
- Komentar yang dimulai dengan "BUG(nama)" seperti "BUG(joe): Ini tidak berhasil" adalah khusus. Godoc akan mengenalinya sebagai bug dan melaporkannya di bagian dokumentasi mereka sendiri.
Godoc Dapat Meringankan Masalah Dokumentasi Anda
Menggunakan Godoc, Anda dapat menjadi lebih produktif dan tidak terlalu khawatir tentang upaya mendokumentasikan program Anda dengan tangan.
Anda harus menjaga dokumentasi Anda tepat, terperinci, dan to the point untuk memudahkan audiens target Anda membaca dan memahami. Penting juga bagi Anda untuk selalu memperbarui komentar kode saat Anda memodifikasi program.
Lihat dokumentasi paket Godoc untuk mempelajari lebih lanjut tentang penggunaan Godoc.
