esbuild dan Redis, Dua Proyek Open Source dengan Dokumentasi Arsitektur yang Sangat Baik

 (johnjago.com)
27 poin oleh GN⁺ 2024-03-26 | 2 komentar | Bagikan ke WhatsApp
  • esbuild dan Redis adalah contoh codebase dengan dokumentasi yang luar biasa.
  • Melalui README, changelog, dokumen arsitektur, dan komentar kode, pengguna baru pun dapat memahami struktur codebase, cara kerjanya, dan alasan di baliknya.
  • Ini menjadi studi kasus yang baik bagi developer yang ingin meningkatkan dokumentasi kode dan arsitektur perangkat lunak mereka.

Mengapa dokumentasi yang baik itu penting

  • Saat menulis perangkat lunak, dokumentasi yang baik sangat penting, terutama ketika orang lain melihat atau berkontribusi pada codebase, atau ketika kita sendiri merujuknya kembali di kemudian hari.
  • Pengguna perangkat lunak sering mengalami kesulitan akibat dokumentasi yang kurang.
  • Jika berkontribusi pada sebuah codebase, semakin baik kualitas dokumentasinya, semakin cepat kita bisa berkontribusi.
  • Kualitas dokumentasi secara langsung maupun tidak langsung memengaruhi pengalaman penulis, kontributor, maupun pengguna.
  • Manfaat dokumentasi yang baik beragam, mulai dari menghemat waktu, meningkatkan kontribusi eksternal pada proyek open source, mencatat keputusan di masa lalu, membuat proyek lebih mudah diakses oleh lebih banyak pengguna, hingga membantu menyusun pemikiran dan menemukan masalah.

Dokumentasi esbuild

  • esbuild adalah bundler JavaScript yang dibuat oleh Evan Wallace.
  • README esbuild berfokus pada pengguna akhir alat tersebut.
  • Melalui tautan ke bagian-bagian utama dokumen dan bagian "Mengapa?", README ini secara singkat menjelaskan alasan memilih esbuild dibanding bundler lain.
  • Dokumen arsitektur esbuild terdiri dari file architecture.md dan development.md di direktori docs.
  • Dokumen arsitektur menjelaskan prinsip-prinsip desain, serta menyertakan grafik untuk menjelaskan konsep, bukan hanya teks.
  • Changelog esbuild sangat rinci, mencakup ringkasan, penjelasan yang diperluas, serta contoh kode sebelum dan sesudah perubahan.

Dokumentasi Redis

  • Redis adalah database in-memory.
  • README Redis memiliki karakteristik baik yang serupa dengan README esbuild, tetapi juga berfokus pada kontributor dan pengguna akhir.
  • Bagian tentang internal Redis mencakup tata letak source code dan penjelasan tentang file-file utama.
  • Komentar kode di dalam source code Redis memberikan penjelasan dalam beberapa paragraf bahkan untuk satu baris kode.

Penutup

  • Banyak proyek open source memiliki dokumentasi yang sangat baik.
  • esbuild dan Redis sangat mengesankan karena dokumentasinya yang luar biasa.
  • Dokumentasi mungkin menimbulkan keterbatasan waktu dalam jangka pendek, tetapi dalam jangka panjang justru menghemat waktu.
  • Untuk proyek yang digunakan atau dikontribusikan oleh banyak orang, tidak membuat dokumentasi adalah sesuatu yang perlu dipikirkan kembali.

Opini GN⁺

  • Contoh dokumentasi esbuild dan Redis menekankan pentingnya dokumentasi yang memudahkan developer memahami dan memelihara codebase.
  • Dokumentasi adalah elemen kunci yang meningkatkan keberlanjutan proyek dan mendorong partisipasi komunitas.
  • Dalam kasus esbuild, selain fungsinya sebagai bundler JavaScript yang cepat, dokumentasi yang sangat baik tampaknya juga berkontribusi pada pertumbuhan proyek.
  • Redis memberi dampak positif pada komunitas developer berkat dokumentasinya yang membantu sistem database in-memory yang kompleks menjadi lebih mudah dipahami.
  • Contoh-contoh ini dapat membantu menyebarkan pentingnya dokumentasi ke proyek open source lain, dan sangat berguna terutama bagi software engineer pemula untuk memahami cara mendokumentasikan proyek mereka sendiri.

Bacaan terkait

2 komentar

 
laeyoung 2024-03-29

README.md esbuild memang sudah bagus, tetapi file architecture.md yang diperkenalkan di tulisan itu juga sangat indah!
 
GN⁺ 2024-03-26
Komentar Hacker News

  • Antirez, pencipta Redis, menulis sebuah artikel di blog pribadinya yang menjelaskan secara rinci pandangannya tentang komentar kode. Ia mengidentifikasi 9 jenis komentar yang digunakan di Redis.

    • Mengejutkan melihat penggunaan "komentar panduan" yang oleh banyak orang dianggap tidak penting.
    • Antirez menyimpulkan bahwa komentar seperti ini bernilai karena membantu memahami kode.
    • Tulisan Antirez

  • Artikel yang ditulis dengan baik ini mencakup contoh konkret dan tangkapan layar tentang bagaimana dokumentasi proyek bisa menjadi sangat baik bagi pengguna/pengembang/kontributor.

    • Membuat orang merefleksikan pekerjaan dan proyek sampingan mereka sendiri, serta memikirkan cara meningkatkan dokumentasi agar lebih mudah dipahami.
    • Seiring berkembang sebagai pengembang, orang cenderung menulis lebih banyak dokumentasi dan pengujian. Beberapa proyek bahkan memiliki lebih banyak dokumentasi dan pengujian daripada kode sebenarnya.
    • Ada pendapat bahwa menulis dokumentasi yang baik membutuhkan kumpulan keterampilan yang berbeda dari menulis kode. Terkadang orang yang tidak terlalu teknis atau tidak berfokus pada pengembangan justru lebih baik dalam menjelaskan.
    • Dokumentasi yang dihasilkan secara otomatis juga bisa berguna, bukan hanya berdiri sendiri tetapi juga bernilai sebagai bahan referensi tambahan.

  • Ini menunjukkan perhatian para maintainer terhadap kualitas repositori.

  • Mengingatkan pada seri "The Architecture of Open Source Applications". Ada wawasan yang menarik.

  • Dokumentasi GitLab punya reputasi sangat baik, tetapi belum banyak perlu digunakan secara langsung. Ada pertanyaan apakah dokumentasi arsitektur mereka juga bagus.

  • Proyek Postgres juga sangat memperhatikan dokumentasi, file readme, dan komentar kode secara detail.

  • Sangat terkesan dengan dokumentasi arsitektur proyek esbuild. Akan sangat membantu jika codebase yang pernah dikerjakan dulu memiliki dokumentasi seperti ini.

    • Ada pertanyaan tentang contoh proyek lain yang memiliki tingkat dokumentasi arsitektur seperti ini.

  • Sangat menyukai changelog proyek open source. Jauh lebih profesional dan informatif daripada entitas lain yang berorientasi profit. Ada kritik bahwa changelog aplikasi bank ING seharusnya fokus pada pemberian informasi alih-alih mencoba lucu.

  • "Kekurangan terbesar dalam komunitas perangkat lunak bebas saat ini bukanlah perangkat lunaknya, melainkan kurangnya dokumentasi bebas yang baik untuk disertakan bersama perangkat lunak bebas."

    • Kutipan dari manual gdb.

  • Disebutkan bahwa Redis tidak lagi open source. Redis adalah perangkat lunak "source-available" di bawah Redis Source Available License v2 (RSALv2) dan Server Side Public License v1 (SSPLv1).

    • Redis Stack dan semua modul Redis yang dibuat oleh Redis Ltd. (misalnya RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, RedisBloom) dilisensikan ganda dengan RSALv2 dan SSPL.
    • Redis Enterprise bersifat closed source dan memerlukan lisensi komersial dari Redis Ltd.
    • Versi Redis yang lebih lama berada di bawah lisensi BSD 3-clause (bebas dan open source). Perubahan lisensi tidak berlaku surut, dan semua kode sumber serta rilis sebelum perubahan tetap menggunakan lisensi BSD 3-clause yang asli. Selama mematuhi ketentuannya, versi-versi tersebut dapat digunakan tanpa batas waktu.
    • Lisensi Redis
    • Lisensi BSD