Saya bergabung dengan proyek skala menengah, yang sudah berjalan selama beberapa tahun. Salah satu masalah adalah bahwa dokumen yang menggambarkan arsitektur tidak pernah ditulis. Sekarang saya diberi tugas untuk menulis deskripsi arsitektur.

Selama saya mengerjakan proyek ini, saya mengumpulkan semua informasi yang saya butuhkan untuk menulis dokumen. Karena saya juga menambahkan beberapa fitur, saya mengidentifikasi beberapa kode, yang jelas-jelas merusak arsitektur seperti yang dijelaskan.

Misalnya, GUI seharusnya menjadi lapisan tipis, tanpa logika bisnis. Itulah yang saya diberitahu. Implementasinya mengandung banyak logika.

Bos saya menugaskan saya tugas, untuk menulis dokumen yang menggambarkan arsitektur sistem. Target audiens adalah pengembang saat ini dan masa depan yang mengerjakan proyek. Saya perlu menggambarkan apa yang seharusnya, tetapi saya juga perlu menjelaskan penyimpangan itu.

Jadi, di mana saya harus menggambarkan masalah ini? Perangkat lunak pelacakan bug? Atau haruskah saya menggambarkan penyimpangan implementasi dari arsitektur dalam dokumen yang menggambarkan arsitektur sistem?

Jika Anda mendokumentasikan desain atau arsitektur sistem yang telah dibangun, dokumen tersebut harus menggambarkannya sebagai buatan dan bukan sebagai desain atau seperti yang dimaksudkan. Jika ada keanehan atau perbedaan dalam arsitektur, maka dokumen ini harus menyebutkan masalah-masalah itu dan menjelaskannya sebanyak mungkin kepada pembaca.

Jika Anda dapat memperoleh informasi dari orang-orang yang telah bekerja pada sistem dari awal (atau setidaknya lebih lama dari yang Anda miliki), akan berguna untuk menangkap lebih banyak informasi tentang apa yang sebenarnya dimaksudkan dan mengapa arsitektur dan desain menyimpang dari ini. niat.

Pada akhirnya, dokumen desain harus berfungsi sebagai panduan untuk kode. Jika dokumen tidak membantu pengembang baru memahami kondisi basis kode saat ini dan bagaimana strukturnya, maka dokumen tersebut tidak berguna.

Dokumen ini harus menjadi dokumen hidup yang digunakan untuk memandu perencanaan dan desain perubahan sistem di masa depan dan kemudian diperbarui sesuai itu, dalam proses pengembangan Anda. Seiring perubahan desain dan evolusi dari waktu ke waktu, dokumen tersebut juga harus membantu pengembang memahami mengapa segala sesuatunya seperti saat ini.

Jika Anda mencari saran untuk menangkap arsitektur, saya menyukai pendekatan yang dianjurkan dalam Standar IEEE 1016-2009 Standar IEEE untuk Teknologi Informasi - Desain Sistem - Deskripsi Desain Perangkat Lunak . Ini memberikan struktur yang masuk akal untuk deskripsi desain, yang dapat digunakan untuk menangkap informasi desain level arsitektur dan detail.

Saya juga akan menganggap penyimpangan ini sebagai bentuk hutang teknis. Mungkin usaha besar, mungkin bahkan proyek kecil, untuk memperbaiki masalah, saya akan merekomendasikan membuat keberadaan utang teknis lebih terlihat. Jika itu berarti Anda menggunakan alat pelacak cacat Anda, maka Anda dapat menempatkan satu atau lebih masalah di sana. Jika Anda memiliki alat lain yang Anda gunakan untuk melacak saran dan peningkatan perangkat lunak, itu mungkin tempat lain untuk meletakkannya.

Ketika memformalkan arsitektur sistem, penting bagi Anda untuk memahami tidak hanya nilai di balik apa yang akan dibawa arsitektur ke meja, tetapi juga untuk memahami dan menghargai apa yang seharusnya.

Tujuan utama Perangkat Lunak atau Arsitektur Teknis adalah untuk mengidentifikasi persyaratan Non-Fungsional yang diwujudkan oleh Atribut Kualitas yang akan mendorong Arsitektur Sistem .

Pada Persyaratan Non-Fungsional:

Persyaratan non-fungsional adalah persyaratan yang menentukan kriteria yang dapat digunakan untuk menilai operasi suatu sistem, bukan perilaku tertentu. Mereka kontras dengan persyaratan fungsional yang menentukan perilaku atau fungsi tertentu. Rencana untuk menerapkan persyaratan fungsional dirinci dalam desain sistem. Rencana untuk menerapkan persyaratan non-fungsional dirinci dalam arsitektur sistem.

Secara umum, persyaratan fungsional menentukan apa yang seharusnya dilakukan sistem dan persyaratan non-fungsional menentukan bagaimana seharusnya suatu sistem. ... Persyaratan non-fungsional sering disebut "atribut kualitas" dari suatu sistem. Istilah lain untuk persyaratan non-fungsional adalah "kualitas", "sasaran kualitas", "kualitas persyaratan layanan", "kendala" dan "persyaratan non-perilaku"

Tentu saja mengidentifikasi persyaratan yang signifikan secara arsitektur masuk akal ketika berada di proyek greenfield, namun ketika bekerja dengan perangkat lunak yang ada, yang terbaik adalah disiplin mungkin. Anda tidak ingin arsitektur perangkat lunak Anda dipengaruhi oleh sistem yang ada.

Arsitektur perangkat lunak agar berwibawa benar-benar perlu 3 hal.

Deklaratif

Ini adalah bagian dari dokumentasi di mana Anda menyatakan BUKAN APA ITU, tetapi bagaimana hal-hal HARUS. Kami melakukan ini melalui penggunaan berbagai Tampilan Arsitektur sistem. Kami mendefinisikan komponen yang seharusnya, bagaimana mereka berinteraksi, dan kemudian kami secara opsional menelusuri ke dalam setiap komponen untuk tampilan yang lebih terperinci yang menyatakan bagaimana sistem harus dirancang.

Ini adalah perbedaan penting. Desain Sistem harus dibatasi oleh Arsitektur Sistem, mereka sebenarnya terpisah tetapi hal-hal terkait.

Alasan

Dasar pemikiran Arsitektur Perangkat Lunak Anda adalah apa yang memberikan legitimasi dan otoritas terhadap keputusan arsitektur yang dibuat. Mungkin keputusan dibuat untuk menggunakan pendengar acara Pub / Sub lebih dari MQ untuk memicu pekerjaan batch dan Anda diagramnya?

Mengapa keputusan ini dibuat? Kami menjelaskan mengapa di bagian Dasar Pemikiran dan menghubungkan kembali penjelasan kami ke Persyaratan Non-Fungsional, Sasaran Atribut Kualitas, atau Persyaratan Penting Secara Arsitektur. (Mis. Pekerjaan harus asinkron dan berulang, Dapat dipertahankan sebagai atribut kualitas mendorong bahwa jika terjadi kegagalan pekerjaan batch yang pekerjaan dapat dimulai kembali melalui pesan MQ, Sistem harus memiliki Kehilangan Pesan Nol dengan komunikasi asinkron, dll. ..)

Risiko

Sekarang setelah Anda mendeklarasikan bagaimana arsitektur seharusnya dan membuktikannya dengan Dasar Pemikiran Anda, Anda sekarang dapat mengidentifikasi Risiko pada kondisi sistem saat ini ke tempat ini tidak tinggal.

(Misalnya. Validasi sisi server sedang diduplikasi pada kode Javascript sisi klien. Ini merupakan pelanggaran prinsip KERING dan ini bertentangan dengan Atribut Kualitas Pemeliharaan. Tidak ada persyaratan Non-Fungsional yang didefinisikan seputar Kinerja di area ini sehingga ada ada Dasar Pemikiran untuk perilaku sistem saat ini)

Risiko Anda juga dapat menggambarkan di mana keadaan saat ini menyimpang dari Arsitektur. Risiko-risiko ini dapat diatasi oleh tim pengembangan sekarang, baik melalui rencana proyek mereka atau dengan menambahkan ini ke dalam simpanan.

Anda benar-benar perlu untuk memutuskan apakah Anda seharusnya mendokumentasikan saat struktur proyek, atau yang diinginkan struktur proyek, atau keduanya.

Anda dapat mendokumentasikan tujuan, dengan tujuan membimbing pengembangan masa depan di sepanjang garis yang diinginkan, dan meningkatkan penyimpangan sebagai bug (mungkin tautan ke bug ini dari bagian dokumen yang relevan). Atau Anda bisa mendokumentasikan kenyataan untuk memberikan pengantar / tinjauan umum terhadap kode. Atau Anda dapat mendokumentasikan kedua sisi berdampingan, sehingga Anda secara bersamaan memiliki panduan untuk pengembangan di masa depan dan deskripsi akurat tentang kode saat ini di satu tempat. Semuanya masuk akal tergantung dari apa dokumen itu seharusnya, jadi saya pikir kami tidak bisa memberi tahu Anda mana yang harus dilakukan.

Anda juga harus ingat bahwa arsitektur yang diinginkan mungkin tidak disetujui secara universal di antara mereka yang terlibat (baik karena mereka menginginkan hal yang berbeda, atau karena beberapa dari mereka telah menyadari bahwa beberapa keinginan bersama yang asli tidak mungkin atau tidak praktis dan oleh karena itu terpaksa menulis kode yang ada yang menyimpang dari tujuan). Jadi, Anda juga perlu tahu apakah Anda memiliki wewenang untuk memutuskan apa yang diinginkan, dan jika tidak, siapa yang berhak . Struktur yang ada setidaknya memiliki keutamaan yang hanya ada satu untuk didokumentasikan!

Tulis di dokumen desain arsitektur apa yang seharusnya, dan untuk setiap konflik Anda menemukan tiket terbuka di pelacak bug yang menggambarkan konflik. Bagian komentar tiket akan menawarkan platform bagi orang-orang yang relevan untuk membahas konflik tertentu.

Perhatikan bahwa resolusi masing-masing tiket ini dapat mengubah implementasi agar sesuai dengan desain - tetapi juga dapat mengubah desain agar sesuai dengan implementasi. Idealnya yang pertama lebih disukai, tetapi kadang-kadang ada kendala teknis dan / atau bisnis yang membuatnya lebih efisien / pragmatis / mungkin untuk memilih nanti. Dalam hal itu, mungkin ide yang baik untuk merujuk pada tiket dari dokumen desain arsitektur, sehingga pembaca masa depan yang tidak mengerti mengapa pilihan desain inferior tertentu dipilih dapat membaca diskusi di tiket dan memahami alasan di balik Itu.

Saya akan cenderung untuk menulis dokumen arsitektur yang diatur dalam 3 bagian utama.

Yang pertama memperkenalkan desain / arsitektur yang awalnya dimaksudkan. Ini akan memungkinkan pengembang / pembaca baru untuk mendapatkan ide tentang apa yang seharusnya dilakukan sistem dan jelas harus dikaitkan dengan persyaratan / penggunaan dll.

Bagian kedua harus menjelaskan dengan sangat jelas apa sebenarnya arsitektur itu. Hal ini memungkinkan pengembang / pembaca baru untuk mendapatkan gambaran tentang kondisi permainan saat ini dan apa yang mereka hadapi jika mereka melihat perangkat lunak (dan berpotensi dokumentasi lainnya). Bagian ini harus dengan jelas menunjukkan perbedaan antara apa yang dimaksudkan dan kenyataan karena ini kemungkinan besar akan menyoroti hal-hal yang sangat salah dengan arsitektur asli (semoga tidak terlalu banyak!) Dan area di mana pintasan / peretasan (mungkin beberapa yang adil jika ada tekanan besar pada tim pengembang) telah dibuat dan persyaratan tidak terpenuhi atau perangkat lunak mulai terlihat dirancang dengan buruk yaitu rapuh, tidak stabil, tidak portabel.

Akhirnya saya pikir bagian yang merinci rekomendasi untuk apa yang perlu terjadi sekarang. Ini harus berupa perubahan apa pun pada arsitektur / desain dan peta jalan untuk perubahan pada perangkat lunak saat ini untuk membuat visi Anda menjadi kenyataan.

Saya pikir ini mencakup (pada level tinggi) apa yang perlu ditangkap. Bagaimana Anda melakukan ini dalam hal subbagian dari dokumen atau perangkat lunak pelacakan bug yang Anda gunakan adalah ke domain tempat Anda bekerja / preferensi pribadi / ukuran tim / anggaran / skala waktu dll.