
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Selama bertahun-tahun, saya telah mengerjakan berbagai jenis proyek—besar, kecil, kacau, berlebihan, "sementara," yang konon terstruktur dengan baik, dan segala sesuatu di antaranya. Namun, satu pola tetap konsisten secara menggelikan: Dokumentasi selalu hilang, kedaluwarsa, atau terkubur di sudut Confluence yang terlupakan yang dijaga oleh stempel waktu 2019. Setiap proyek   memiliki dokumentasi. mengklaim Setiap tim   akan memperbaruinya. berjanji Dan setiap pengembang dengan percaya diri berkata, "Jangan khawatir, saya akan menuliskannya nanti," yang, seperti yang kita semua tahu, adalah padanan dokumentasi untuk mengatakan  "ceknya ada di pos." Setelah menyaksikan siklus ini berulang lebih sering daripada yang ingin saya akui, saya menyadari sesuatu yang sederhana namun sangat benar: 
 
 Dokumentasi hanya bertahan jika hidup sedekat mungkin dengan kode—karena pengembang (termasuk saya sendiri) adalah makhluk yang malas. Dan dari situ, kesadaran lain muncul—masalah utama dengan dokumentasi yang kedaluwarsa adalah fakta bahwa sebagian besar tim tidak menganggapnya sebagai bagian dari siklus pengembangan utama, meninggalkannya untuk nanti atau puas dengan beberapa spesifikasi pra-pengembangan yang sudah mereka miliki di suatu tempat di Confluence. Untuk menulis dokumentasi yang bermakna, mari kita diskusikan terlebih dahulu jenis dokumentasi apa yang ada untuk komponen perangkat lunak: Cara Mendokumentasikan Kode (yang Mungkin Benar-benar Digunakan Pengembang) Setelah Anda menerima bahwa dokumentasi harus hidup dekat dengan kode, pertanyaan selanjutnya adalah   menyusunnya. bagaimana Dalam praktiknya, saya menemukan bahwa dokumentasi yang baik bukanlah satu artefak—melainkan ekosistem kecil berlapis, masing-masing melayani tujuan dan audiens yang berbeda. Untuk proyek yang saya sebutkan (ditulis dalam Java + Spring Boot), kami mengidentifikasi empat jenis dokumen utama: 1. Spesifikasi Klien Ini adalah dokumen konvensional yang biasanya disusun oleh ahli domain. Idealnya, mereka kaya akan bahasa yang merata dan memberikan deskripsi kasus bisnis yang tidak bergantung pada kode—dengan kata lain, semua yang dibutuhkan insinyur untuk benar-benar memahami masalah yang ada. Sayangnya, dalam kenyataannya, dokumen-dokumen ini seringkali berakhir disimpan di suatu tempat di Confluence, dibagikan dengan tim di awal proyek, dan kemudian hampir tidak pernah diperbarui lagi. Jangan salah paham: dokumen-dokumen ini  . penting Mengekstrak pengetahuan dari pakar domain harus menjadi prioritas utama bagi tim rekayasa mana pun. Tetapi spesifikasi berkembang, tenggat waktu membuat semua orang stres, dan dokumen asli itu perlahan tapi pasti menjadi dasar yang kedaluwarsa. Pengetahuan tentang perubahan persyaratan, kasus tepi, dan pivot proyek berakhir hidup dalam kode—atau lebih buruk lagi!—di kepala pengembang senior. Untuk mengatasi ini, kami berhenti menulis spesifikasi dalam file Word acak atau halaman Confluence yang ditakdirkan untuk dilupakan dan memindahkannya sedekat mungkin ke garis depan:  repositori kode. Kami mulai menyimpannya sebagai file Markdown (.md) di dalam repo, biasanya di folder docs/. Dalam lingkungan microservice yang besar, dokumen-dokumen ini bahkan dapat membenarkan repositori khusus yang ditautkan sebagai submodule Git. Submodule sering diabaikan, tetapi mereka adalah cara yang ampuh untuk menjaga ekosistem multi-repo tetap teratur. Untuk bacaan lebih lanjut tentang submodule, saya sangat merekomendasikan posting blog ini -  . tautan 2. README – Pintu Depan untuk Manusia Jika spesifikasi klien adalah ensiklopedia, README adalah pintu depan. Namun, ini adalah salah satu bagian dokumentasi yang paling diabaikan dalam proyek perangkat lunak. Ironisnya, hampir setiap platform kontrol versi—GitHub, GitLab, Bitbucket—secara otomatis merender README tepat di halaman proyek utama. Ini adalah hal pertama yang dilihat pengembang mana pun saat mendarat di repositori. Meskipun demikian, README seringkali sangat kosong, kedaluwarsa, atau dipenuhi dengan "TODO: tulis dokumentasi nanti" yang mengerikan, yang tentu saja tidak pernah terjadi. README yang bagus bukanlah pilihan. Ini adalah satu-satunya dokumen yang paling mungkin dibaca karena hanya membutuhkan  . Dan karena berada di akar repo, pengembang lebih mungkin untuk memperbaruinya saat mengerjakan kode. Ini adalah dokumentasi yang hidup di jalur hambatan terkecil. nol klik README yang ditulis dengan baik harus menjawab pertanyaan terpenting yang dimiliki pengembang dalam beberapa menit pertama setelah menemukan proyek: 
 
 
 
 
 
 
  pernyataan tujuan dan konteks yang ringkas - tanpa embel-embel pemasaran. Apa yang dilakukan layanan/proyek/komponen ini? -  instruksi runtime, variabel lingkungan, penyiapan dependensi, dan perintah khusus proyek apa pun. Bagaimana cara menjalankannya secara lokal? -  pengujian unit, pengujian integrasi, penyiapan data pengujian, dan alat terkait pengujian apa pun. Bagaimana cara mengujinya? -  penjelasan singkat tentang tata letak direktori, modul utama, dan di mana menemukan bagian kode yang penting. Bagaimana struktur proyeknya? -  Skrip penyebaran, catatan CI/CD, izin yang diperlukan, atau nuansa platform. Bagaimana cara menyebarkannya?  tautan ke dokumentasi yang dihasilkan, catatan arsitektur, referensi API, dan dokumen desain terpusat. Di mana saya bisa membaca lebih lanjut? - README adalah gerbang ke proyek. Ini menetapkan harapan, mengurangi waktu orientasi, dan memberi setiap insinyur—baru atau berpengalaman—titik orientasi yang jelas. Ketika dipelihara dengan benar, itu menjadi dokumen tunggal yang paling berharga di seluruh repositori. 3. JavaDocs – Dokumen yang Membuat Kompilator Mengganggu Anda untuk Memeliharanya JavaDocs—biasanya tidak terlihat, sering terlupakan, tetapi sangat penting ketika ada yang rusak. Dalam praktiknya, mendokumentasikan proyek Java seringkali terbagi menjadi dua ekstrem: baik  , atau   karena "kode mendokumentasikan dirinya sendiri." Kebenaran, seperti biasa, ada di antaranya. mengomentari setiap baris trivial tidak ada komentar sama sekali Untuk proyek kami, kami membuat keputusan sadar untuk mendokumentasikan  . Itu berarti: hanya apa yang benar-benar diperlukan 
 
 
 
 
 menggunakan   sehingga istilah domain cocok persis dengan spesifikasi bisnis bahasa yang merata menjelaskan   di balik keputusan yang tidak jelas, bukan   yang sudah diungkapkan oleh kode mengapa apa mendokumentasikan kelas domain inti, antarmuka, dan alur kerja yang kompleks menghindari dinding komentar yang hanya mengulangi nama metode dalam bentuk yang bertele-tele JavaDocs, bila digunakan dengan benar, berfungsi sebagai dokumentasi tingkat mikro yang mengklarifikasi niat tanpa mengotori kode. Dan tidak seperti halaman Confluence, JavaDocs memiliki keuntungan bawaan: 
 
 Kompilator benar-benar mengeluh ketika mereka tidak sinkron. Jika Anda mengganti nama parameter tetapi lupa tag JavaDoc, build akan mengingatkan Anda. Jika Anda menghapus metode tetapi meninggalkan referensi komentar yang basi, IDE akan menyala seperti pohon Natal. Gesekan yang lembut inilah yang membuat JavaDocs cenderung lebih akurat daripada bentuk dokumentasi lainnya—mereka menyebalkan jika diabaikan. Untuk menjaga semuanya tetap terpusat dan menghindari "pulau dokumentasi," kami juga menggunakan  . Doxygen Doxygen adalah alat penghasil dokumentasi yang banyak digunakan dalam pengembangan perangkat lunak. Meskipun terutama digunakan dalam komunitas C++, kami menggunakannya untuk menggabungkan JavaDocs menjadi referensi HTML yang konsisten dan dapat dijelajahi. Ia memiliki sejumlah fitur yang tidak ditawarkan JavaDoc, mis., diagram kelas untuk hierarki dan konteks kerja sama, lebih banyak halaman ringkasan, dan banyak lagi. Ini memberi kami pandangan yang bersih dan terpadu dari seluruh basis kode tanpa bergantung pada petunjuk IDE yang tersebar. 4. Kode Bersih – Dokumentasi yang Tidak Perlu Anda Pelihara Terakhir, bentuk dokumentasi yang paling diremehkan juga merupakan yang paling sedikit dihormati oleh pengembang sampai mereka benar-benar membutuhkannya:  kode bersih. Komentar menua. Spesifikasi melenceng. README diabaikan. JavaDocs bisa basi. Tetapi kode yang ditulis dengan baik—jelas, disengaja, dan ekspresif—  dokumentasi. adalah Seperti yang dikatakan Uncle Bob dengan terkenal,  "Kode bersih dibaca seperti prosa yang ditulis dengan baik." Dan dalam praktiknya, itu berarti: 
 
 
 
 
 
 
 kelas dan metode dengan nama yang mengungkapkan tujuan mereka fungsi yang melakukan satu hal dan melakukannya dengan baik terminologi domain digunakan secara konsisten di seluruh tidak ada kecerdikan demi kecerdikan itu sendiri tidak ada "perilaku kejutan" yang tersembunyi di dalam efek samping tidak ada abstraksi yang terlalu dalam yang membutuhkan gelar PhD untuk dipahami Kode bersih adalah satu-satunya artefak yang dijamin akan bertahan dari refactor, sprint, pergantian staf, dan kekacauan organisasi. Selalu sinkron dengan perilaku sistem karena—itu   perilaku sistem. adalah Aturan sederhana muncul bagi kami seiring waktu:  Jika Anda memerlukan satu paragraf komentar untuk menjelaskan sebuah metode, masalah sebenarnya adalah metodenya. Ketika kode ekspresif, segalanya menjadi lebih mudah → JavaDocs menjadi lebih ringan dan lebih fokus → README menyusut karena orientasi menjadi jelas → spesifikasi menjadi lebih jelas karena model domain mencerminkan kosakata bisnis. Kode bersih tidak menghilangkan kebutuhan akan dokumentasi; itu  . menjangkarkannya Ini memastikan bahwa semua bentuk dokumentasi lainnya—spesifikasi, README, JavaDocs—memperkuat kebenaran alih-alih mengkompensasi implementasi yang tidak jelas. Pada akhirnya, kode bersih adalah dokumentasi yang tidak memerlukan pemeliharaan, integrasi CI, atau perangkat lunak. Ini adalah penjelasan yang paling jujur dan andal tentang apa yang sebenarnya dilakukan sistem. Menyatukan Semuanya — Saluran Dokumentasi yang Hidup Setelah memperbaiki cara kami menulis dokumentasi, langkah terakhir adalah memastikan dokumentasi tersebut tidak hanya dibuat—tetapi terus dikirimkan dan selalu dapat diakses. Untuk itu, kami membangun saluran dokumentasi yang mengubah spesifikasi, file README, dan JavaDocs kami menjadi satu, terpadu  . portal dokumentasi yang hidup Karena kami ingin dokumentasi kami sedekat mungkin dengan kode kami, kami memutuskan untuk menyebarkan semuanya melalui  , yang memberi kami solusi hosting yang mudah, dikontrol versi, yang terikat langsung ke basis kode. Github Pages tidak khusus untuk Github (GitLab, misalnya, juga memiliki GitLab pages) - ini adalah fitur rapi lainnya dari sistem kontrol versi populer yang saya rekomendasikan untuk bacaan lebih lanjut -  . GitHub Pages tautan Untuk mengkompilasi semuanya menjadi satu set halaman yang kohesif, kami menggunakan  Sphinx. Sphinx adalah generator dokumentasi yang kuat yang ditulis dalam Python. Ia mengambil file sumber yang ditulis dalam reStructuredText atau Markdown dan menerjemahkannya ke berbagai format output, termasuk HTML, PDF, dan ePub. Sphinx menangani struktur, navigasi, dan tema. Doxygen memberi Sphinx JavaDocs yang dibuat secara otomatis menggunakan plugin  , memberi kami referensi API yang dapat dijelajahi sepenuhnya langsung dari kode sumber. Sementara itu, README utama berfungsi sebagai titik masuk segera bagi pengembang yang menjelajahi repositori, ditautkan dengan mulus ke situs dokumentasi yang dihasilkan. Breathe Setiap penggabungan ke dalam main memicu pekerjaan CI yang membangun kembali dokumen, memastikan portal mencerminkan perubahan kode terbaru, pembaruan API, dan keputusan desain. Tidak ada yang hidup terisolasi. Tidak ada yang memerlukan sinkronisasi manual. Dan yang terpenting—tidak ada yang lebih dari satu klik. Ini mengubah dokumentasi kami dari artefak statis menjadi ekosistem yang terus diperbarui yang benar-benar digunakan oleh pengembang, karena terintegrasi langsung ke dalam alur kerja harian mereka dan hidup tepat di samping kode. Kesimpulan — Dokumentasi adalah Tanggung Jawab Kami, Bukan Beban Kami Pada akhirnya, menulis dokumentasi bukanlah pilihan. Ini adalah bagian dari pekerjaan kami sebagai profesional rekayasa. Rekan tim di masa depan bergantung padanya. Orientasi bergantung padanya. Pemeliharaan, keandalan, dan bahkan kejelasan arsitektur bergantung padanya. Tetapi menerima tanggung jawab itu tidak berarti dokumentasi harus menyakitkan. Dengan menjaga dokumen tetap dekat dengan kode, mengotomatiskan apa pun yang dapat diotomatiskan, dan mengandalkan alat pintar seperti Markdown, JavaDocs, Doxygen, dan Sphinx, kami menghilangkan gesekan yang biasanya menghancurkan upaya dokumentasi. Kami mengubah sesuatu yang secara tradisional terasa seperti tugas menjadi perpanjangan alami dari pengembangan sehari-hari. Dan ketika kami memasangkan itu dengan kode yang bersih, README yang baik, dan spesifikasi yang kaya domain, seluruh ekosistem menjadi mandiri. Dokumentasi tidak harus sempurna—ia hanya perlu dapat diakses, akurat, dan hidup. Ketika kita membangun sistem yang mendorong pengembang untuk memperbarui dokumen semudah mereka menulis kode, semua orang mendapat manfaat: tim, produk, dan yang terpenting, orang malang yang mewarisi proyek enam bulan kemudian. Dokumentasi yang baik tidak membuat kita kurang malas. Itu hanya membuat kemalasan kompatibel dengan membangun perangkat lunak yang hebat.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

Audio ini dihasilkan dalam bahasa asal cerita!

Sekiranya Dokumentasi Anda Memerlukan Dua Klik untuk Dibuka, Tahniah – Ia Sudah Ketinggalan Zaman

About Author

KOMEN

GANTUNG TANDA

ARTIKEL INI DIBENTANGKAN DALAM

Related Stories

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps