ARCHITECTURE.md (2021): Spesifikasi Teknis Struktur Proyek

 (matklad.github.io)
1 poin oleh GN⁺ 2024-02-26 | 1 komentar | Bagikan ke WhatsApp
  • Proyek open source berskala 10k–200k baris kode dapat mengurangi biaya bagi kontributor baru untuk memahami struktur kode dengan menaruh dokumen ARCHITECTURE di samping README dan CONTRIBUTING
  • Dalam proyek yang asing, masalah yang lebih besar bukanlah penulisan patch yang kira-kira 2 kali lebih lambat, melainkan butuh waktu 10 kali lebih lama untuk menemukan bagian mana yang harus diperbaiki
  • Dokumen ini sebaiknya memuat secara singkat struktur tingkat tinggi dan hal-hal yang tidak sering berubah, serta lebih cocok ditinjau beberapa kali setahun daripada terus disinkronkan dengan kode
  • Komponen intinya adalah gambaran umum masalah dan codemap, yang menunjukkan modul-modul besar beserta relasinya agar dapat menjawab “di mana kode yang menangani X?”
  • Catat nama-nama penting, invariant arsitektur, batas antarlapisan dan antarsistem, serta cross-cutting concerns; mendorong pencarian berdasarkan nama alih-alih tautan langsung dapat mengurangi beban pemeliharaan

Biaya yang Dikurangi oleh Dokumen ARCHITECTURE

  • Dalam proyek open source, perbedaan terbesar antara orang yang sesekali berkontribusi dan pengembang inti adalah apakah mereka mengetahui arsitektur fisik proyek tersebut
  • Dalam codebase yang asing, file cenderung dibaca secara berurutan seperti potongan logika yang disusun dalam urutan acak
  • Pengembang yang sudah pernah memberi kontribusi bermakna memiliki peta kode di dalam kepala, sehingga bisa langsung menuju lokasi yang diperlukan; jika tidak ada, mereka bahkan bisa memindahkan kode tersebut
  • File ARCHITECTURE adalah cara berbiaya rendah untuk memperkecil kesenjangan ini
  • Dokumen harus singkat
    • Karena semua orang yang berkontribusi berulang kali perlu membacanya
    • Semakin singkat, semakin kecil kemungkinan dokumen menjadi tidak valid akibat perubahan di masa depan
  • Patokannya adalah memasukkan hal-hal yang tidak sering berubah ke dalam ARCHITECTURE
    • Jangan berusaha terus-menerus menyinkronkannya dengan kode
    • Sebagai gantinya, tinjau kembali beberapa kali dalam setahun

Apa yang Harus Dimuat

  • Pertama, rangkum masalah yang dipecahkan proyek pada tingkat gambaran umum
  • Setelah itu, tulis codemap yang cukup terperinci
    • Jelaskan modul-modul berukuran besar dan hubungan di antara mereka
    • Harus menjawab “di mana letak bagian yang melakukan X?”
    • Juga harus menjawab “apa fungsi hal yang sedang saya lihat ini?”
  • Jangan masuk terlalu dalam ke cara kerja internal tiap modul
    • Isi seperti itu dipindahkan ke dokumen terpisah, atau lebih baik lagi, ke dokumentasi inline
    • Codemap adalah peta negara, bukan atlas per provinsi
  • Dalam proses menulis codemap, struktur proyek juga dapat ikut diperiksa
    • Anda dapat memeriksa apakah hal-hal yang ingin ditempatkan berdekatan di codemap juga berdekatan dalam hasil menjalankan tree .
  • Sebutkan secara eksplisit nama file, modul, dan tipe yang penting
    • Hindari tautan langsung karena dapat rusak seiring waktu
    • Sebagai gantinya, arahkan pembaca untuk mencari simbol berdasarkan nama, sehingga mereka juga dapat menemukan item dengan nama serupa yang relevan tanpa menambah beban pemeliharaan
  • Invariant arsitektur harus ditulis secara eksplisit
    • Invariant penting sering kali muncul dalam bentuk bahwa sesuatu “tidak ada”
    • Misalnya, dalam pengembangan web, fakta bahwa lapisan model tidak bergantung pada view bisa sulit diketahui hanya dengan membaca kode
  • Batas antara lapisan dan sistem juga harus ditandai
    • Batas mengisyaratkan informasi tentang implementasi sistem di baliknya
    • Batas juga membatasi semua kemungkinan implementasi
    • Karena batas yang baik sulit ditemukan secara acak di dalam kode, mendokumentasikannya sangat berguna
  • Setelah codemap, tambahkan bagian terpisah untuk cross-cutting concerns
  • Contoh yang dapat dijadikan rujukan dapat dilihat di architecture.md milik rust-analyzer

Bacaan terkait

1 komentar

 
GN⁺ 2024-02-26
Opini Hacker News

  • Saya suka ide ini, dan menurut saya penjelasan arsitektur juga pantas punya tempat di README, terlepas dari ukuran repositori
    Misalnya, saya merasa penting agar semua pembaca bisa melihat dan memahami alur kerja, jadi saya sengaja memasukkan diagram sekuens Mermaid[1] di README utama[2]
    [1] https://mermaid.js.org/syntax/sequenceDiagram.html
    [2] https://github.com/hbcondo/revenut-app?tab=readme-ov-file#-w...

    • Akan cukup keren kalau ada alat yang bisa membuat diagram Mermaid dari bahasa alami. Layak dipikirkan

  • Kedengarannya seperti saran yang sangat bagus
    Saya berharap alat untuk memvisualisasikan arsitektur sistem yang sedang berjalan menjadi lebih baik. Rasanya aneh bahwa membaca kode atau melihat berkas Markdown masih dianggap cara paling mutakhir. Kalau beruntung, mungkin ada diagram Mermaid
    Saya ingin arsitektur menampakkan dirinya sendiri secara real time. Akan bagus kalau observabilitas skala makro sudah tertanam secara bawaan; saya rasa itu juga akan membantu semua orang memahami komputasi dengan lebih baik dan membantu umat manusia mengaugmentasi dirinya sendiri

    • Akan bagus jika visualisasi seperti dep-tree ditambahi pencarian kata kunci atau pencarian vektor LLM. Saat mengajukan kueri, berkas dan klaster yang relevan akan disorot

  • Untuk proyek open source dengan banyak kontributor sementara, ini terlihat seperti model yang rendah perawatan. Untuk proyek yang punya engineer khusus, ADR juga layak dipertimbangkan
    ADR memang membutuhkan lebih banyak pemeliharaan, tetapi karena mencatat “mengapa dilakukan begitu” dan “alternatif yang sempat dipertimbangkan”, ADR sangat berguna saat melakukan desain ulang
    Referensi: https://adr.github.io/

    • Di sini, menurut saya ungkapan yang lebih tepat adalah “bersama”, bukan “sebagai pengganti”
      ARCHITECTURE.md memuat kondisi arsitektur saat ini, sementara ADR adalah catatan keputusan yang membawa kita sampai ke sana. Keduanya sangat berguna
    • Di perusahaan kami juga ada dokumen tidak berguna yang ditulis para arsitek, dan kebanyakan seperti ini
      Microservices, Kafka, Kubernetes: alasannya, pengguna saat ini 4 ribu orang, tapi bagaimana kalau nanti jadi 1 miliar?
      GraphDB: alasannya, bagaimana kalau SQL saja tidak cukup?
      ElasticSearch: alasannya, bagaimana kalau selain statistik juga perlu full-text search?
      Namun sebagian besar dokumen seperti ini pada akhirnya hanyalah singkatan dari “saya ingin mencoba arsitektur/teknologi baru karena menarik, rekan saya di FAANG memakainya, saya sudah membaca buku itu, kelihatannya bagus di CV”
      Setelah mereka pindah ke perancangan proyek besar berikutnya, tim kami harus terus menyinkronkan lebih banyak service daripada jumlah anggota tim, beserta DB dan teknologi di atas. Tentu saja, masalah seperti ini dianggap jauh lebih sederhana daripada membuat “keputusan arsitektur besar”

  • Tiba-tiba terpikir, semua IDE yang pernah saya pakai menampilkan struktur folder proyek di sisi kiri sebagai pohon direktori standar. Apakah ada IDE yang memungkinkan kita menjelajahi proyek sebagai graf dependensi?

    • Ini bukan jawaban langsung atas pertanyaannya, tetapi sepertinya intinya adalah “ingin memvisualisasikan struktur berkas dengan lebih baik”
      Menurut saya representasi seperti daftar isi kurang cocok. Dalam alur kerja coding saya belakangan ini, saya membuka terminal, menjalankan ranger di dalamnya, lalu berpindah tab ke terminal itu saat ingin menjelajahi struktur direktori kiri-kanan. Saya membuka VSCode dan di terminal terpisah bagian atas menjalankan terminal biasa, bagian bawah menjalankan Ranger. Midnight Commander juga bisa; pada dasarnya TUI file explorer apa pun cukup
      Saya juga mulai memasukkan peta kode ke berkas architecture.md proyek. Dengan menjalankan tree -L , kita bisa mendapatkan diagram pohon struktur berkas pada kedalaman yang diinginkan, yang cocok dimasukkan ke Markdown. Saya menambahkan output itu ke Markdown, lalu menempelkan komentar di belakang tiap berkas/folder untuk menjelaskan kegunaannya dalam kurang dari 10 kata
      Ranger - https://github.com/ranger/ranger
      Midnight Commander - https://midnight-commander.org/
    • Saya juga memikirkan hal yang persis sama
      Ada dua ide tentang seperti apa bentuknya
      Pertama, beberapa pohon direktori yang mengorganisasi berkas secara ortogonal dengan symbolic link. Struktur direktori umum biasanya dipisah menjadi client/server, tetapi bagaimana kalau kita ingin membaginya berdasarkan fitur? IDE bisa membuatnya jauh lebih mudah
      Kedua, sejalan dengan arah tulisan ini, saya ingin IDE membantu membuat bookmark, berpindah di antaranya, dan memudahkan menjelaskan kode kepada orang lain. Kadang saya ingin meninggalkan komentar lalu, saat diklik, melompat ke lokasi lain di codebase. Jika hal-hal seperti ini dirangkai, kita bisa menyusun narasi yang menjelaskan cara kerja di seluruh codebase
      Saya penasaran apakah ada orang yang mengerjakan hal semacam ini
    • Dalam praktiknya akan seperti apa? Misalnya, bagaimana menangani dependensi siklik?
    • Mungkin yang diinginkan adalah multitree

  • Menurut saya kita perlu berhati-hati agar tidak terlalu memperluas apa yang dikatakan penulis di sini ke proyek perangkat lunak secara umum
    Pada proyek open source besar dengan banyak kontributor yang minim konteks, dokumen seperti ini sangat layak dipelihara. Namun pada proyek kerja kecil, saya melihat dokumen yang dikomit developer pada akhirnya semuanya menjadi tidak terpelihara

    • Saya pernah beberapa kali mengadakan sesi arsitektur dengan tim, dan itu selalu bernilai
      Setidaknya, kami jadi tahu bahwa anggota tim punya pemikiran yang sangat berbeda satu sama lain tentang arsitektur saat ini dan arsitektur ideal. Membuat hal itu eksplisit saja sudah cukup menjadi alasan untuk membuat dokumen
      Selain itu, “dokumen tidak akan dipelihara” adalah alasan yang sangat lemah untuk tidak membuat dokumen. Sebab dokumen apa pun, bahkan yang sudah lama atau sedikit keliru, tetap lebih baik daripada “tidak ada dokumen”

  • Beberapa tahun lalu, di salah satu proyek sampingan besar, saya pernah bereksperimen dengan pendekatan serupa
    https://github.com/shipmight/shipmight/blob/master/src/ARCHI...
    Di bagian atas tiap file, saya menaruh pohon tautan ke file ARCHITECTURE.md lain di dalam repositori. Contohnya seperti ini: ARCHITECTURE.md <- lokasi saat ini, backend/ARCHITECTURE.md, backend/api/ARCHITECTURE.md, backend/cli/ARCHITECTURE.md, backend/ui/ARCHITECTURE.md, backend/utils/ARCHITECTURE.md, frontend/ARCHITECTURE.md, internal-charts/ARCHITECTURE.md

  • Makin singkat, makin kecil kemungkinannya menjadi tidak valid karena perubahan di masa depan. Aturan praktis utama untuk ARCHITECTURE adalah menuliskan hanya hal-hal yang tidak sering berubah. Jangan mencoba menyinkronkannya dengan kode
    Interface lebih kecil kemungkinannya berubah, dan juga lebih sulit diubah. Ini adalah sudut pandang Parnas tentang kriteria yang digunakan saat memecah sistem menjadi modul
    Saya setuju bahwa codebase sulit dipahami. Penamaan “pola” memang membantu sampai batas tertentu, tetapi pada akhirnya tetap harus membaca cukup banyak
    Di GitHub, pesan commit per file sering terasa seperti penjelasan. Mungkinkah itu lebih berguna?

  • Di semua proyek yang pernah saya ikuti, saat onboarding saya mendapat diagram arsitektur dan penjelasan singkat tentang komponen-komponennya
    Jadi saya terkejut bahwa hal ini tidak begitu umum di open source

    • “Penjelasan komponen” itulah masalahnya. Karena harus ada seseorang yang melakukannya
      Proyek open source tidak punya hari pertama kerja karyawan, jadi tidak ada pengenalan seperti ini
      Jika waktunya tidak sangat banyak, penjelasan semacam ini biasanya kurang bagus. Karyawan diharapkan butuh beberapa minggu sampai bisa melakukan sesuatu sendiri, tetapi kami sebagai konsultan keamanan mendapat penjelasan yang benar-benar baru setiap 2 minggu. Masalahnya, penjelasan seperti ini bersifat dadakan dan tidak terstruktur, dan pembicaranya, karena kutukan pengetahuan, menyebutkan terlalu banyak detail yang tidak relevan
      Mungkin akan lebih baik jika seseorang yang baru datang ke repositori menulisnya sekali, lalu setelah itu hanya dipelihara. Pilihan kedua terbaik adalah, alih-alih siapa pun menjelaskan secara dadakan setiap kali, luangkan sekitar 1 menit untuk memikirkan apa yang perlu dimasukkan dan dikeluarkan, lalu tuliskan. Seperti yang dikatakan penulis, file ini harus menjelaskan arsitektur tingkat tinggi proyek dan harus singkat. Semua kontributor berulang harus membacanya, dan makin singkat, makin kecil pula kemungkinan ia menjadi tidak valid karena perubahan di masa depan

  • Saya selalu merasa ini praktik yang sangat berguna. Banyak proyek memiliki beberapa file inti, atau paket/modul, tempat sebagian besar perubahan terjadi
    Jika kontributor baru atau kontributor yang kembali setelah lama absen bisa cepat memahaminya, waktu untuk mulai mengerjakan proyek akan berkurang banyak
    Saya pernah menambahkan file arsitektur ke proyek di beberapa tempat kerja, dan [0], [1] responsnya bagus. Tidak sempurna, tetapi lebih baik daripada tidak ada
    [0]: https://github.com/zapier/zapier-platform/pull/324
    [1]: https://github.com/stripe/stripe-cli/blob/master/ARCHITECTUR...

    • Apakah ada cara untuk melihat hal seperti ini secara otomatis di GitHub? Misalnya semacam heatmap perubahan file

  • Dulu saya menyukai standar dokumentasi/diagram-as-code kecil seperti ini
    Seperti README-driven development, ARCHITECTURE.md, ADR, arc42, C4, dan sebagainya
    Sekarang saya hanya menaruh vault Obsidian di folder /docs dalam repositori git
    Alih-alih memakai standar orang lain, saya terus merapikan dan merefaktor dokumentasi seperti mengelola catatan pribadi di Obsidian
    Awalnya saya ingin memakai subset Markdown bersama yang bisa berjalan baik di GFM GitHub maupun Obsidian, tetapi saya menyerah, dan sekarang saya memakai Markdown gaya Obsidian apa adanya, termasuk fitur khas seperti plugin Dataview dan template
    Mermaid dan LaTeX sudah bawaan di Obsidian, dan ada juga plugin PlantUML. Untuk gambar/diagram visual, saya memakai Canvas bawaan, DrawIO, dan Excalidraw