Apakah ada standar untuk mendokumentasikan arsitektur tingkat tinggi program?

Saya adalah pengembang amatir dan semua program saya sampai sekarang cukup sederhana untuk didokumentasikan dalam kode. Saat membaca kode jelas apa yang saya lakukan ini dan itu tindakan (tes standar saya adalah melihat kode 6 bulan kemudian dan memahami semuanya pada awalnya membaca - dan saya memiliki rentang memori pendek).

Saya sekarang dihadapkan dengan program yang melebihi kemampuan saya untuk mengingat berbagai interaksi di antaranya

• kode itu sendiri
• indeks dalam database
• interaksi antara berbagai modul (kode inti "pekerja" dan yang "perpustakaan")

Dokumentasi saya saat ini adalah papan tulis di mana saya memiliki semua jenis kotak dan panah yang mengarah ke kode, ke indeks basis data, untuk tindakan yang dieksekusi, untuk menyatakan perubahan, dll. Hanya untuk referensi, bagian dari kekacauan:

Pertanyaan saya adalah apakah ada set standar, atau serangkaian praktik terbaik (dinamai dalam arti bahwa ini adalah serangkaian praktik yang dikelompokkan berdasarkan nama tertentu) untuk dokumentasi produk yang lebih kompleks.

Apa kata kunci yang harus saya cari (upaya umum pada "standar arsitektur perangkat lunak dokumen" dan variasi serupa biasanya mengarah ke perangkat lunak untuk alur kerja atau membangun sistem CAD arsitektur).

Saya juga berharap bahwa mungkin tidak ada praktik umum terbaik untuk deskripsi tingkat tinggi dan bahwa setiap orang membangun filosofi sendiri.

Tidak ada satu standar yang dipatuhi setiap orang. Proyek perangkat lunak dapat sangat bervariasi (pikirkan: helloworld.py vs kode dalam pesawat ulang-alik).

Salah satu metode yang sangat umum adalah dengan menggunakan model 4 + 1 . Alih-alih mencoba menjejalkan semuanya menjadi satu gaya dokumen, metodologi ini memecah desain menjadi lima komponen:

• The Pembangunan tampilan
• The Logical tampilan
• The Fisik tampilan
• The Proses tampilan
• Skenario

Berbagai pandangan menggambarkan produk dari empat perspektif berbeda. Skenario di mana kasus penggunaan tinggal, dan menggambarkan interaksi dari pandangan lain.

Catatan: Ini adalah model konseptual, dan tidak terikat pada alat tertentu.

Anda dapat membaca lebih lanjut di sini:

1. 4 + 1 model tampilan arsitektur (wikipedia)
2. Blueprints Arsitektur — The “4 +1” Lihat Model Arsitektur Perangkat Lunak (kertas IEEE - pdf)

IMHO UML bukan alat yang berfungsi dengan baik untuk mendokumentasikan arsitektur perangkat lunak dunia nyata. Diagram kelas berguna, tetapi gunakan tingkat abstraksi yang seringkali terlalu rendah untuk tujuan ini. Use case diagram biasanya terlalu "tingkat tinggi" dan kehilangan aspek-aspek tertentu. Jenis diagram UML lain memiliki masalah yang sama (Agar adil, diagram paket, diagram penempatan, diagram komponen dapat mendokumentasikan aspek arsitektur tertentu, tetapi secara pribadi saya tidak pernah merasa sangat berguna).

Jika Anda mencari cara yang praktis dan pragmatis untuk mendokumentasikan arsitektur tingkat tinggi, saya sarankan untuk membuat diri Anda terbiasa dengan diagram aliran data . Ini mudah dipahami dan memiliki keunggulan yang dapat ditingkatkan ke berbagai tingkat abstraksi. Saya telah menemukan mereka yang paling berguna untuk mendokumentasikan berbagai jenis sistem. Sayang sekali mereka tidak menemukan jalan mereka ke UML, tetapi meskipun demikian Anda menemukan banyak alat - bahkan yang gratis seperti Dia atau DrawIO - untuk membuat diagram ini.

Sebagai catatan tambahan, mengapa Anda memerlukan "indeks dalam database" dalam dokumentasi tingkat tinggi? Saya pikir mereka adalah detail implementasi dari model data Anda (relasional?), Dan jika Anda menambahkannya atau tidak - menurut pengalaman saya - lebih merupakan masalah kinerja dan optimisasi.

Unified Modeling Language (UML) adalah bahasa pemodelan tujuan-umum, pengembangan, di bidang rekayasa perangkat lunak, yang dimaksudkan untuk memberikan cara standar untuk memvisualisasikan desain sistem.

Saya pikir kami dulu melakukan yang lebih baik. UML sepertinya membuang bayi itu dengan air mandi. Dalam menyediakan Bahasa Pemodelan yang Terpadu itu menghapuskan perbedaan antara arsitektur dan implementasi. Atau jika itu tidak dimaksudkan untuk ini sepertinya akan berpengaruh.

Saya telah melihat beberapa model monster UML dan terus terang mereka tidak melakukan apa pun untuk saya yang tidak bisa dilakukan oleh kode, dan melakukannya dengan lebih baik.