Apa itu dokumentasi kode?

Dokumentasi kode bertindak sebagai peta bagi mereka yang berinteraksi dengan basis kode, membantu mereka menavigasi apa yang dilakukan setiap potong kode, cara kerjanya, cara menggunakannya, dan bagaimana semua potongan kode terintegrasi. Mendokumentasikan kode membantu tim pengembangan memelihara kode sumber dengan lebih baik sekaligus membimbing pemangku kepentingan lain yang mungkin perlu memahami dan bekerja dengan kode, seperti analis keamanan siber, ilmuwan data, insinyur DevOps, manajer produk dan proyek, insinyur QA, dan penulis teknis.

Dokumentasi sebagai kode atau "dokumen sebagai kode" memperlakukan dokumentasi seperti kode perangkat lunak. Pendekatan ini mengelola dokumentasi menggunakan alat yang sama seperti kode sumber, termasuk sistem kontrol versi untuk meninjau dan melacak perubahan, pengujian otomatis untuk mengidentifikasi masalah pemformatan dan gaya, dan integrasi berkelanjutan/pengiriman berkelanjutan (CI/CD) untuk memperbarui dan menerapkan dokumentasi.

Sementara dokumentasi kode mencakup praktik yang lebih luas dalam mendokumentasikan kode, dokumen sebagai kode adalah strategi khusus dan pendekatan yang lebih teknis untuk menulis dokumentasi.

Struktur dokumentasi kode akan tergantung pada siapa audiens dan bagaimana dokumentasi akan digunakan. Berikut adalah beberapa jenis dokumentasi yang umum:

• Dokumentasi tingkat rendah
  
  
• Dokumentasi tingkat tinggi
  
  
• Dokumentasi internal
  
  
• Dokumentasi eksternal

Dokumentasi tingkat rendah biasanya mengacu pada komentar dalam baris di dalam kode. Sebagai salah satu metode paling dasar untuk menulis dokumentasi, anotasi ini menjelaskan baris atau blok kode tertentu.

String dokumentasi atau docstrings adalah teknik dokumentasi tingkat rendah lainnya. Mereka muncul sebelum kelas, fungsi, metode, atau definisi modul. Docstrings memiliki format terstruktur yang menyatakan tujuan, contoh penggunaan, fungsionalitas, parameter, dan nilai hasil.

Komentar dalam baris lebih cocok untuk menentukan logika ketika tidak dapat diperoleh dari memeriksa kode itu sendiri atau untuk kode yang berdasarkan algoritma lebih kompleks. Sementara itu, docstrings dapat diekstraksi untuk dokumentasi antarmuka pemrograman aplikasi (API) dan memberikan bantuan kontekstual di dalam lingkungan pengembangan terintegrasi (IDE).

Tidak seperti dokumentasi tingkat rendah yang menggambarkan berbagai bagian kode sebagai entitas terpisah, dokumentasi tingkat tinggi mencakup detail tentang peran mereka dalam alur kerja arsitektur yang lebih luas. Jenis dokumentasi perangkat lunak ini mencakup diagram alur dan diagram Bahasa Pemodelan Terpadu (UML) yang menggambarkan arsitektur kode, dokumen desain yang menguraikan logika bisnis dan bagaimana kode selaras dengan persyaratan produk, dan spesifikasi struktur basis kode atau repositori kode.

Dokumentasi teknis ini ditujukan untuk penggunaan internal dalam suatu perusahaan. Contohnya termasuk konvensi dan standar pengodean dan dokumen proses tentang bagaimana tim membangun perangkat lunak. Panduan untuk menyiapkan lingkungan pengembangan juga termasuk dalam dokumentasi internal.

Dokumentasi yang digunakan langsung oleh pengguna ini ditujukan untuk pengembang dan pengguna lain di luar perusahaan. Misalnya, dokumentasi API menjabarkan kelas, fungsi, metode, dan modul yang tersedia dari API publik proyek perangkat lunak. Dokumentasi eksternal juga dapat terdiri dari file konfigurasi, catatan integrasi, dan file README.

File README ditulis dalam markdown, bahasa markup ringan untuk memformat teks biasa. Ini berisi informasi tentang fitur proyek, dependensi, instruksi instalasi, perintah antarmuka baris perintah (CLI), dan opsi untuk mendapatkan bantuan dan dukungan. Proyek sumber terbuka juga menambahkan detail lisensi dan pedoman kontributor untuk mengirimkan permintaan penggabungan untuk menggabungkan perbaikan bug atau perubahan kode ke cabang utama repositori kode.

Menulis kode dengan cara yang sederhana dan jelas dapat menjadi bentuk dokumentasi tersendiri. Namun, dokumentasi yang baik tetap penting dan memberikan manfaat berikut:

• Meningkatkan kolaborasi

• Meningkatkan kemudahan pemeliharaan

• Mempercepat pengembangan perangkat lunak

• Menyederhanakan orientasi

Kode yang didokumentasikan dengan baik meningkatkan kolaborasi dan komunikasi yang lebih baik dalam tim pengembangan. Anggota dapat memanfaatkan dokumentasi kode sebagai bahasa bersama untuk melakukan tinjauan kode, mendiskusikan perubahan kode, dan membuat keputusan sebagai tim.

Dokumentasi memfasilitasi pemfaktoran ulang kode, pemeliharaan, dan pengoptimalan kinerja. Selama proses debug, pengembang dapat menggunakan dokumentasi sebagai titik referensi untuk menemukan kesalahan pengodean dan menentukan akar masalah.

Dokumentasi yang baik membuka jalan bagi pengembangan yang cepat, menghemat waktu dalam mencari tahu fungsionalitas kode dan mengalihkan fokus ke penerapan pembaruan kode yang tepat. Ini juga membantu melacak perubahan, memastikan tim dapat mengimbangi basis kode yang terus berkembang.

Dokumentasi kode membantu anggota tim baru dalam mempelajari sistem internal suatu basis kode. Mereka dapat mempelajari desain dan struktur kode lebih cepat, memungkinkan mereka untuk dengan cepat berkontribusi pada proyek.

Kode dan dokumentasi bekerja bersama-sama, sehingga mereka juga harus berkembang bersama. Dan beberapa pedoman untuk menulis kode juga berlaku untuk menulis dokumentasi. Berikut adalah beberapa tip yang dapat membantu:

• Tetapkan standar dokumentasi kode

• Integrasikan dokumentasi dengan pengodean

• Kejelasan dan keringkasan adalah kuncinya

• Keputusan pengodean dokumen 

• Perbarui secara berkala

Seperti konvensi pengodean, standar juga harus diikuti untuk dokumentasi kode. Standar ini mencakup pemformatan yang konsisten, seperti indentasi, jeda baris, dan spasi untuk dokumentasi tingkat rendah. Sementara itu, templat dan alat dokumentasi kode dapat membantu gaya dan struktur untuk dokumentasi API dan dokumentasi tingkat tinggi dan eksternal lainnya.

Ini mungkin melibatkan penambahan docstrings setelah menyelesaikan fungsi atau memasukkan komentar dalam baris saat menerapkan algoritma atau logika yang rumit. Menulis dokumentasi saat pemrograman dapat membantu pengembang mengartikulasikan proses pemikiran dan keputusan mereka, memastikan detail penting tidak hilang selama proses ini. Mungkin diperlukan waktu ekstra pada awalnya, tetapi ini dapat menjadi bagian alami dari proses pengodean dan mempercepat debug, pengoptimalan, dan pemfaktoran ulang pada kemudian hari.

Dokumentasi yang berlebihan dapat menghambat keterbacaan kode. Pengembang harus memprioritaskan penulisan kode yang sederhana dan jelas, kemudian menambahkan dokumentasi yang diperlukan yang sesuai dengan kode itu.

Dalam hal keringkasan, menemukan keseimbangan yang tepat sangat penting. Misalnya, fragmen kode pendek dan sederhana mungkin tidak memerlukan dokumentasi sama sekali. Di sisi lain, algoritma yang lebih canggih memerlukan dokumentasi yang menjelaskan logika yang mendasarinya dengan cara yang dapat dipahami oleh pengembang dengan berbagai tingkat pengalaman.

Ini termasuk desain, arsitektur, logika, dan pilihan algoritmik. Mendokumentasikan keputusan pengodean ini, baik melalui dokumen internal tingkat tinggi maupun basis pengetahuan bersama, memberikan konteks untuk setiap perubahan yang akan dilakukan pada masa mendatang.

Tim pengembangan harus melakukan tinjauan dan pembaruan berkala pada dokumentasi kode mereka untuk memastikannya akurat, lengkap, dan relevan, mencerminkan keadaan perangkat lunak saat ini. Memasukkan dokumentasi ke dalam proses peninjauan kode dapat membantu pembaruan rutin.

Sebagian besar IDE memiliki ekstensi atau plugin untuk menghasilkan dokumentasi kode, tetapi kerangka kerja dan alat lain juga dapat membantu mengotomatiskan proses ini. Berikut adalah beberapa pembuat dokumentasi umum:

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen mendukung berbagai bahasa pemrograman, seperti C, C++, Java, PHP, dan Python. Pembuat dokumentasi ini memungkinkan rendering markdown dan dapat menghasilkan dokumentasi dalam format HTML, PDF, dan XML. Doxygen dapat disesuaikan melalui file konfigurasi dan memberikan kemampuan untuk menghasilkan diagram yang menggambarkan hierarki visual dan korelasi antara kelas dan fungsi.

GitBook memberikan antarmuka pengguna untuk menulis dan menerbitkan dokumentasi sebagai situs web, yang dapat membuatnya lebih efisien untuk membuat dokumentasi internal dan eksternal. Platform ini juga memiliki fitur sinkronisasi dengan repositori GitHub atau GitLab.

Alat Javadoc mengurai komentar dokumentasi dalam kode sumber Java untuk menghasilkan dokumentasi API dalam format HTML. Alat ini dapat mendokumentasikan kelas, konstruktor, bidang, antarmuka, dan metode.

Mirip dengan Javadoc, JSDoc menghasilkan dokumentasi API untuk proyek JavaScript. Komunitas sumber terbukanya telah mengembangkan templat dan alat untuk menyesuaikan dokumentasi.

Sphinx terutama dibuat untuk Python tetapi juga dapat digunakan untuk bahasa pemrograman lainnya. Alat ini mendukung markdown dan bahasa markup miliknya sendiri yang disebut reStructuredText. Sphinx dapat membuat dokumentasi dalam berbagai format output dan fitur referensi silang untuk menautkan ke elemen kode lainnya.

Pembuat dokumentasi terbatas pada anotasi yang mereka temui di seluruh kode sumber. AI generatif mengambil dokumentasi selangkah lebih jauh, menganalisis cuplikan kode tertentu dan menambahkan komentar kode yang menggambarkan tujuan dan fungsinya. Banyak model bahasa besar (LLM) untuk kode memiliki kemampuan bawaan untuk menghasilkan dokumentasi.

Misalnya, IBM Bob dapat menghasilkan baris komentar untuk satu metode atau semua metode dalam suatu kelas. Alat serupa lainnya termasuk GitHub Copilot, JetBrains AI Assistant, Mintlify, dan Tabnine.

Seperti halnya sistem kecerdasan buatan lainnya, pengembang tetap harus meninjau output dari alat dokumentasi kode yang didukung AI untuk memastikan kelengkapan dan keakuratannya.