Dokumen spesifikasi teknis "Architecture.md (2021)"

Rekomendasi penulisan ARCHITECTURE.md

• Sangat disarankan agar maintainer proyek open source menambahkan dokumen ARCHITECTURE di samping README dan CONTRIBUTING.
• Dokumen ini menjelaskan arsitektur tingkat tinggi proyek, dan karena harus dibaca oleh para kontributor yang berulang kali berkontribusi, sebaiknya dibuat singkat.
• Dokumen ARCHITECTURE sebaiknya hanya memuat hal-hal yang tidak sering berubah, dan alih-alih mencoba menyelaraskannya dengan kode, lebih baik meninjaunya beberapa kali dalam setahun.

Tujuan dan pentingnya dokumen

• Pengetahuan tentang arsitektur fisik proyek merupakan perbedaan terbesar antara kontributor umum dan pengembang inti.
• Jika belum akrab dengan proyek, menulis patch membutuhkan waktu 2 kali lebih lama, dan mencari tahu lokasi yang perlu diubah dalam kode membutuhkan waktu 10 kali lebih lama.
• File ARCHITECTURE adalah cara yang efektif untuk menutup kesenjangan ini, sekaligus memberi kesempatan untuk merefleksikan struktur proyek.

Susunan dokumen

• Dokumen harus dimulai dengan ikhtisar dari sudut pandang baru terhadap masalah, lalu memberikan peta kode terperinci yang menjelaskan hubungan antar modul.
• Sebutkan file, modul, dan tipe yang penting, tetapi alih-alih menautkannya secara langsung, dorong pembaca untuk mencarinya berdasarkan nama agar tidak memerlukan pemeliharaan.
• Invarians arsitektural perlu ditunjukkan secara eksplisit, dan batas antar lapisan harus dijelaskan.

Invarians arsitektural dan batas

• Invarians penting sering kali dinyatakan sebagai ketiadaan sesuatu, sehingga sulit dipahami hanya dengan membaca kode.
• Batas antar lapisan atau sistem secara implisit memuat informasi tentang implementasi sistem dan membatasi semua implementasi yang mungkin.

Concern lintas-ujung

• Setelah menyelesaikan peta kode, perlu ditambahkan bagian terpisah untuk concern lintas-ujung.
• Contoh yang baik untuk dokumen ARCHITECTURE adalah architecture.md milik rust-analyzer.

GN⁺ berpendapat:

• Dokumen ARCHITECTURE berperan penting dalam membantu pemahaman proyek dan membuat kontributor baru lebih cepat terbiasa dengan codebase.
• Dokumen ini memperjelas struktur proyek serta menyoroti prinsip dan batas arsitektur yang penting, sehingga membantu pengembang memahami sistem dengan lebih baik.
• Adopsi dokumen ARCHITECTURE di komunitas open source dapat berkontribusi pada pertumbuhan dan pemeliharaan proyek yang berkelanjutan, dan ini merupakan pendekatan yang sangat bermanfaat serta menarik bagi para pengembang.

[GN⁺]

Komentar Hacker News

• Jika Anda mengelola proyek open source dan jumlah baris kodenya sekitar 10k-200k, saya sangat menyarankan untuk menambahkan dokumen ARCHITECTURE.

  • Idenya bagus, tetapi menurut saya arsitektur bisa dimasukkan ke Readme terlepas dari ukuran repositori. Misalnya, saya sengaja menempatkan diagram urutan Mermaid di Readme utama agar semua pengguna bisa memahami alur kerjanya.

• Pendekatan ini sangat baik sebagai model dengan perawatan rendah untuk proyek open source yang memiliki banyak kontributor ad hoc. Untuk proyek yang memiliki engineer khusus, sebaiknya pertimbangkan ADRs. Ini memang membutuhkan lebih banyak perawatan, tetapi sangat membantu saat membangun ulang karena mencatat "mengapa" dan "alternatif yang dipertimbangkan".

• Beberapa tahun lalu saya bereksperimen dengan sesuatu yang mirip di salah satu proyek sampingan besar saya:

  • Di bagian atas setiap file ada pohon tautan ke file ARCHITECTURE.md lainnya.

• Semua IDE menampilkan struktur folder proyek di sisi kiri dengan pohon direktori standar. Apakah ada IDE yang mendukung penelusuran proyek dengan graf dependensi?

• Kita perlu berhati-hati saat memperluas apa yang ditulis penulis di sini ke proyek perangkat lunak pada umumnya. Pada proyek open source besar dengan banyak kontributor yang memiliki sedikit konteks, menjaga dokumen seperti ini memang bernilai. Tetapi pada proyek kerja kecil, semua dokumen yang pernah saya lihat ditulis oleh developer pada akhirnya tidak terurus.

• Semakin pendek dokumen, semakin kecil kemungkinan menjadi tidak valid karena perubahan di masa depan. Ini adalah aturan utama dokumen ARCHITECTURE — tuliskan hanya hal-hal yang kecil kemungkinannya sering berubah. Jangan mencoba menyinkronkannya dengan kode.

  • Antarmuka lebih kecil kemungkinannya untuk berubah dan [lebih sulit!] (Parnas, kriteria yang digunakan untuk memecah sistem menjadi modul).

• Saat onboarding di semua proyek, saya menunjukkan diagram arsitektur dan penjelasan singkat tentang komponennya.

  • Sekarang saya terkejut melihat betapa jarangnya hal ini di open source.

• Ini adalah praktik yang sangat berguna. Banyak proyek memiliki beberapa file inti (atau package/module/dll.) tempat sebagian besar perubahan terjadi. Jika kontributor baru (atau kontributor yang kembali setelah lama) bisa memahami ini dengan cepat, waktu untuk mulai berkontribusi pada proyek bisa dipersingkat secara signifikan.

• Saya penggemar standar kecil berupa dokumen/kode seperti ini:

  • README-driven development
  • ARCHITECTURE.md
  • ADRs
  • arc42
  • C4
  • dan seterusnya.
  • Sekarang saya menaruh vault Obsidian di dalam folder /docs pada repositori git.
  • Daripada menggunakan standar milik orang lain, saya mengatur dan merefaktor dokumentasi seperti saat saya mengelola catatan pribadi di Obsidian.
  • Saya sempat mencoba menggunakan subset Markdown umum yang berfungsi baik di GitHub (GFM) maupun Obsidian, tetapi akhirnya menyerah dan memakai Markdown Obsidian beserta fitur-fiturnya yang khusus.
  • Obsidian memiliki Mermaid dan LaTeX bawaan, serta plugin untuk PlantUML.
  • Untuk gambar/diagram visual, tersedia Canvas, DrawIO, dan Excalidraw bawaan.

• Pernah dibahas saat itu:

  • Architecture.md - Feb 2021 (153 komentar)