
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Selama bertahun-tahun, saya telah mengerjakan berbagai macam proyek—besar, kecil, kacau, terlalu direkayasa, yang "sementara", yang konon terstruktur dengan baik, dan segala sesuatu di antaranya. Namun satu pola yang secara lucu konsisten: Dokumentasinya selalu hilang, usang, atau terkubur di sudut Confluence yang terlupakan yang dijaga oleh stempel waktu 2019. Setiap proyek   memiliki dokumentasi. mengklaim Setiap tim   akan menjaganya tetap diperbarui. berjanji Dan setiap pengembang dengan percaya diri berkata, "Jangan khawatir, saya akan menuliskannya nanti," yang, seperti yang kita semua tahu, adalah padanan dokumentasi dari mengatakan  "ceknya ada di pos." Setelah menyaksikan siklus ini berulang lebih sering daripada yang ingin saya akui, saya menyadari sesuatu yang sederhana namun brutalnya 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 usang adalah fakta bahwa sebagian besar tim tidak menganggapnya sebagai bagian dari siklus pengembangan utama, meninggalkannya untuk nanti atau melakukannya 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 sebuah 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   cara menyusunnya. bagaimana Dalam praktiknya, saya menemukan bahwa dokumentasi yang baik bukanlah satu artefak tunggal - itu adalah ekosistem kecil berlapis-lapis, 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 seorang ahli domain. Idealnya, mereka kaya dengan bahasa yang ada di mana-mana dan memberikan deskripsi kasus bisnis yang tidak bergantung pada kode—dengan kata lain, segala sesuatu yang dibutuhkan seorang insinyur untuk benar-benar memahami masalah yang dihadapi. Sayangnya, dalam kenyataannya, dokumen-dokumen ini sering kali berakhir tersimpan 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 ahli domain harus menjadi prioritas utama bagi tim teknik mana pun. Tetapi spesifikasi berkembang, tenggat waktu membuat semua orang stres, dan dokumen asli tersebut perlahan tapi pasti menjadi fondasi yang usang. Pengetahuan tentang perubahan persyaratan, kasus tepi, dan pivot proyek akhirnya hidup dalam kode—atau lebih buruk lagi!—di kepala pengembang senior. Untuk mengatasi hal 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 ini adalah cara yang ampuh untuk menjaga ekosistem multi-repo tetap terorganisir. 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 sering kali kosong secara mengejutkan, usang secara menyakitkan, atau dipenuhi dengan "TODO: tulis dokumentasi nanti," yang tentu saja tidak pernah terjadi. README yang baik bukanlah opsional. Ini adalah satu dokumen yang paling mungkin benar-benar dibaca karena membutuhkan  . Dan karena berada di root repo, pengembang lebih cenderung memperbaruinya saat mengerjakan kode. Ini adalah dokumentasi yang hidup di jalur resistensi terkecil. nol klik README yang ditulis dengan baik harus menjawab pertanyaan terpenting yang dimiliki pengembang dalam beberapa menit pertama saat menemukan sebuah proyek: 
 
 
 
 
 
 
  pernyataan tujuan dan konteks yang ringkas - tidak ada omong kosong pemasaran. Apa yang dilakukan layanan/proyek/komponen ini? -  instruksi runtime, variabel lingkungan, pengaturan dependensi, dan perintah spesifik proyek apa pun. Bagaimana cara menjalankannya secara lokal? -  pengujian unit, pengujian integrasi, pengaturan data pengujian, dan alat terkait pengujian apa pun. Bagaimana cara mengujinya? -  penjelasan singkat tentang tata letak direktori, modul utama, dan di mana menemukan bagian penting dari kode. 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 dalam proyek. Ini menetapkan ekspektasi, 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 Kompiler Mengganggu Anda untuk Memeliharanya JavaDocs - biasanya tidak terlihat, sering dilupakan, tetapi sangat penting ketika ada yang rusak. Dalam praktiknya, mendokumentasikan proyek Java sering kali terbagi menjadi dua ekstrem: baik  , atau   karena "kodenya mendokumentasikan diri sendiri." Kebenarannya, seperti biasa, ada di antaranya. memberi komentar berlebihan pada setiap baris sepele 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 yang ada di spesifikasi bisnis bahasa yang ada di mana-mana 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 mengulang nama metode dalam bentuk yang bertele-tele JavaDocs, bila digunakan dengan benar, berfungsi sebagai dokumentasi tingkat mikro yang mengklarifikasi niat tanpa mengacaukan kode. Dan tidak seperti halaman Confluence, JavaDocs memiliki keuntungan bawaan: 
 
 Kompiler 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 membiarkan referensi komentar yang basi, IDE akan menyala seperti pohon Natal. Gesekan ringan inilah yang membuat JavaDocs cenderung tetap lebih akurat daripada bentuk dokumentasi lainnya—mereka mengganggu untuk diabaikan. Untuk menjaga semuanya tetap terpusat dan menghindari "pulau dokumentasi," kami juga menggunakan  . Doxygen Doxygen adalah alat generator dokumentasi yang banyak digunakan dalam pengembangan perangkat lunak. Meskipun terutama digunakan di komunitas C++, kami menggunakannya untuk mengagregasi JavaDocs ke dalam referensi yang konsisten dan dapat dijelajahi—halaman HTML. Ini 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 dihargai oleh pengembang sampai mereka benar-benar membutuhkannya:  kode bersih. Komentar menua. Spesifikasi menyimpang. README diabaikan. JavaDocs bisa basi. Tetapi kode yang ditulis dengan baik—jelas, disengaja, dan ekspresif—  dokumentasi. adalah Seperti yang dikatakan oleh Paman Bob yang 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 kepintaran untuk kepentingannya sendiri tidak ada "perilaku kejutan" yang tersembunyi dalam efek samping tidak ada abstraksi yang tidak perlu dalam yang membutuhkan PhD untuk dipahami Kode bersih adalah satu-satunya artefak yang dijamin bertahan dari refactor, sprint, pergantian staf, dan kekacauan organisasi. Kode ini selalu sinkron dengan perilaku sistem karena—itu   perilaku sistem. adalah Aturan sederhana muncul bagi kami seiring waktu:  Jika Anda membutuhkan satu paragraf komentar untuk menjelaskan sebuah metode, masalah sebenarnya adalah metodenya. Ketika kode ekspresif, segala sesuatu yang lain 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; ia  . menjaganya 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 alat apa pun. Ini adalah penjelasan yang paling jujur dan andal tentang apa yang sebenarnya dilakukan sistem. Menyatukan Semuanya — Pipeline Dokumentasi Langsung Setelah menyempurnakan cara kami menulis dokumentasi, langkah terakhir adalah memastikan bahwa itu tidak hanya dibuat—tetapi terus dikirimkan dan selalu dapat diakses. Untuk itu, kami membangun pipeline dokumentasi yang mengubah spesifikasi kami, file README, dan JavaDocs menjadi satu, terpadu  . portal dokumentasi langsung Karena kami ingin dokumentasi kami hidup sedekat mungkin dengan kode kami, kami memutuskan untuk menyebarkan semuanya melalui  , yang memberi kami solusi hosting yang mudah, dikontrol versi, dan terhubung langsung ke basis kode. Github Pages tidak khusus untuk Github (GitLab, misalnya, juga memiliki halaman GitLab) - ini adalah fitur rapi lainnya dari sistem kontrol versi populer yang saya rekomendasikan untuk dibaca lebih lanjut -  . GitHub Pages tautan Untuk mengkompilasi semuanya menjadi satu set halaman yang kohesif, kami menggunakan  Sphinx. Sphinx adalah generator dokumentasi canggih yang ditulis dalam Python. Ini mengambil file sumber yang ditulis dalam reStructuredText atau Markdown dan menerjemahkannya ke dalam berbagai format keluaran, 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 root berfungsi sebagai titik masuk langsung bagi pengembang yang menjelajahi repositori, menautkan dengan mulus ke situs dokumentasi yang dihasilkan. Breathe Setiap merge ke 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 teknik. 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 diotomatisasi, dan mengandalkan alat cerdas 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 bersih, README yang baik, dan spesifikasi yang kaya domain, seluruh ekosistem menjadi mandiri. Dokumentasi tidak harus sempurna—itu hanya perlu dapat diakses, akurat, dan hidup. Ketika kita membangun sistem yang mendorong pengembang untuk memperbarui dokumen semudah menulis kode, semua orang diuntungkan: tim, produk, dan yang terpenting, jiwa 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 diproduksi dalam bahasa asli cerita!

Jika Dokumentasi Anda Membutuhkan Dua Klik untuk Dibuka, Selamat - Itu Sudah Usang

About Author

KOMENTAR

HANG TAG

ARTIKEL INI DISAJIKAN PADA

Related Stories

How to biohack your intelligence — with everything from sex to modafinil to MDMA

Why do you need JWT in your ASP.NET Core project?

IdeaOps: Why Every Request is a Company Asset in Product Development

How to Fetch Large Data Files Through GitHub API

How to biohack your intelligence — with everything from sex to modafinil to MDMA

Why do you need JWT in your ASP.NET Core project?

IdeaOps: Why Every Request is a Company Asset in Product Development

How to Fetch Large Data Files Through GitHub API

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps