Ada istilah menarik dalam dunia koding yaitu "Good code documents itself". Meski demikian tidak semua orang setuju, Mereka yang menolak menyebut bahwa tiap kode itu sendiri tidak akan memberi tahu kita tentang keputusan dan alasan di balik penulisan kode tersebut. Atau tentang struktur dan abstraksi tingkat yang lebih tinggi dari kode yang disusun. Semua ini membutuhkan elaborasi dalam dokumentasi.

Secara umum dokumentasi kode adalah kumpulan gambar dan deskripsi tertulis yang mudah dipahami yang menjelaskan apa yang dilakukan basis kode dan bagaimana basis kode dapat digunakan. Di dalamnya bisa juga berisi komentar penjelasan sederhana di atas fungsi dan blok, atau buku pegangan programmer yang lengkap dengan gaya preskriptif tentang apa yang harus dan tidak boleh dilakukan.

Mulia Nasution Direktur Produk Refactory adalah orang yang mendukung “Good code documents itself”. Menurutnya kode yang baik seperti dokumentasi. Misalnya untuk menghitung luas lingkaran

r = 5
l = 22/7 * r * r

Itu lebih sulit dipahami. Tapi kalau documents itself

pi = 22/7
radius = 5
circleArea = pi * radius^2

“Lebih panjang, tapi lebih mudah dimengerti. Terutama orang lain yang tidak familiar dengan kode di project/app tersebut.Code readability is one of the most important qualities of good code,” katanya.

Menurut Mulia, bahkan orang yang menulis kode, apabila tidak konsisten mengerjakan project dalam 1-2 bulan, saat kembali lagi ke project yang lama, bisa lupa dan harus mengingat ulag. Ini mengapa jika kodenya nggak documents itself, akan sangat merepotkan. “Aku lebih suka yang to the point dan practical. Tapi di kasus tertentu, perlu menjelaskan hal-hal yang lebih ke arah konsep, bisnis proses, diagram, dll,” katanya.

Mulia mencontohkan beberapa kode yang memiliki dokumentasi yang sangat baik. “Contohnya kalau perlu menjelaskan konsep, dll seperti dokumentasi Stripe misalnya. Menjelaskan banyak hal, dari konsep, diagram, cara menggunakan, cara menguji, dan lainnya,” jelas Mulia.

Menemukan proyek baru, menarik, dan terdokumentasi dengan baik dalam bahasa favoritmu bisa sangat mengasyikkan dan menyenangkan. Lalu bagaimana jika kita harus mengerjakan proyek baru yang tidak memiliki dokumentasi baik, maka kita akan bekerja lebih keras, tidak efisien, atau bahkan harus mengulang banyak hal.

Ini mengapa salah satu hal yang penting dilakukan oleh programmer adalah membuat dokumentasi kode yang baik. Hal ini akan memudahkan siapapun yang hendak bekerja dan membantu proyek kita. Lalu siapa yang diuntungkan dalam pengerjaan code yang baik? Kode yang didokumentasikan dengan baik bermanfaat bagi banyak orang, misalnya :

1. Junior Engineer

Karena dalam bahasa yang sederhana dan mudah dimengerti, dokumentasi membantu pengembang junior dan anggota tim baru merasa percaya diri untuk terjun ke basis kode. Ini mencegah frustrasi dan pengabaian awal tugas karena terlalu rumit terlalu cepat.

Ini juga membantu bagi pengembang junior untuk menulis dokumentasi mereka sendiri sehingga mereka dapat membagikan kode mereka dengan orang lain dan agar mereka dapat lebih memahami kode mereka.

2. Senior Engineer

Dengan meluangkan waktu untuk mendokumentasikan sekarang, pengembang senior menghabiskan lebih sedikit waktu untuk menjelaskan kode mereka kepada orang lain di masa mendatang.

Mereka juga dapat menulis kode yang lebih kompleks. Dokumentasi bahasa sederhana memungkinkan orang lain menggunakannya seperti kotak hitam, tanpa harus memahami cara kerja bagian dalamnya.

Dalam program Intensive Pairing, dokumentasi digunakan agar para peserta program bisa belajar lebih efisien. Mereka akan dituntut untuk belajar secara mandiri, tidak hanya copy paste, tapi juga paham mengapa sebuah kode ditulis. Selain itu adanya Pairing diharapkan bisa meminimalisir kesalahan.

Sebagai seorang programmer, kita mungkin pernah mendengar tentang prinsip jangan mengulang kode yang buruk sebagai kunci untuk menulis kode yang bersih dan ringkas. Alih-alih mengulangi blok kode yang sama karena minimnya dokumentasi, ada baiknya, membaca dokumentasi sebelum memulai project, dengan adanya Pairing kita bisa belajar mana yang efektif dan tidak.

Sumber: https://www.olioapps.com/blog/the-value-of-code-documentation/