Bir programın üst düzey mimarisini belgelemek için bir standart var mı?

Ben amatör bir geliştiriciyim ve şimdiye kadar tüm programlarım kod içinde belgelenecek kadar basitti. Kodu okurken böyle ve böyle bir eylem ne yaptığını açıktı (benim standart test 6 ay sonra koda bakmak ve ilk okuma her şeyi anlamak - ve kısa bellek süresi var).

Şu anda aralarındaki çeşitli etkileşimleri hatırlama kapasitemi aşan bir programla karşı karşıyayım

• kodun kendisi
• veritabanındaki dizinler
• çeşitli modüller arasındaki etkileşimler ("işçi" çekirdek kodu ve "kütüphane" modülleri)

Mevcut belgelerim, kod, veritabanı dizinleri, yürütülen eylemler, durum değişikliği vb. İçin işaret eden her türlü kutu ve okun bulunduğu bir beyaz tahta. Sadece referans olarak, karışıklığın bir parçası:

Benim sorum, daha karmaşık ürünlerin belgelenmesi için standart veya adlandırılmış en iyi uygulamaların (bunun belirli bir ad altında gruplandırılmış bir grup uygulama olduğu anlamına gelir) olup olmadığıdır.

Aramam gereken anahtar kelimeler nelerdir ("belge yazılım mimarisi standartlarına" genel girişimler ve benzer varyasyonlar genellikle iş akışları veya bina mimarisi CAD sistemleri için yazılıma yol açmıştır).

Ayrıca, üst düzey açıklamalar için genel en iyi uygulamaların bulunmamasını ve herkesin kendi felsefesini oluşturmasını bekliyorum.

Herkesin uyduğu tek bir standart yoktur. Yazılım projeleri büyük farklılıklar gösterebilir (düşünün: helloworld.py vs uzay mekiğindeki kod).

Çok yaygın bir yöntem 4 + 1 modelini kullanmaktır . Her şeyi tek bir belge stiline sıkıştırmak yerine, bu yöntem tasarımı beş bileşene ayırır:

• Kalkınma görünümü
• Mantıksal görünüm
• Fiziksel görünüm
• Proses görünüşüdür
• Senaryolar

Çeşitli görüşler ürünü dört farklı perspektiften tanımlar. Senaryolar, kullanım örneklerinin yaşadığı ve diğer görünümlerin etkileşimini açıklayan senaryolardır.

Not: Bu kavramsal bir modeldir ve belirli bir araca bağlı değildir.

Daha fazlasını buradan okuyabilirsiniz:

1. 4 + 1 mimari görünüm modeli (wikipedia)
2. Mimari Planlar — Yazılım Mimarisinin “4 + 1” Görünüm Modelini (IEEE belgesi - pdf)

IMHO UML, gerçek dünya yazılım mimarisini belgelemek için iyi çalışan bir araç değildir . Sınıf diyagramları yararlıdır, ancak bu amaç için genellikle çok düşük olan bir soyutlama seviyesi kullanın. Kullanım senaryoları genellikle çok "üst düzey" dir ve bazı yönleri gözden kaçırır. Diğer UML diyagramı türleri de benzer sorunlara sahiptir (Adil olmak gerekirse, paket şemaları, dağıtım şemaları, bileşen şemaları belirli mimari yönleri belgeleyebilir, ancak kişisel olarak bunları asla çok yararlı bulmadım).

Üst düzey mimarileri belgelemenin çalışan, pragmatik bir yolunu arıyorsanız , veri akış diyagramlarını tanımanızı öneririz . Bunların anlaşılması kolaydır ve farklı soyutlama düzeylerine ölçeklendirilebilme avantajına sahiptirler. Onları farklı tür sistemleri belgelemek için en kullanışlı buldum. UML'ye girmediklerini çok kötü buluyorlar, ancak yine de bu diyagramları yapmak için birçok araç - hatta Dia veya DrawIO gibi ücretsiz araçlar buluyorsunuz .

Yan not olarak, üst düzey bir belgede neden "veritabanındaki dizinler" gereklidir ? Bence (ilişkisel?) Veri modelinizin bir uygulama detayıdır ve bunları eklerseniz ya da eklemezseniz - deneyimlerime göre - daha fazla performans ve optimizasyon meselesidir.

Birleşik Modelleme Dili (UML), bir yazılımın tasarımını görselleştirmek için standart bir yol sağlamayı amaçlayan, yazılım mühendisliği alanında genel amaçlı, gelişimsel, modelleme dilidir.

Sanırım eskiden daha iyisini yapardık. UML bebeği banyo suyuyla dışarı atmış gibiydi. Birleştirilmiş Modelleme Dili sağlarken, mimari ve uygulama arasındaki ayrımı kaldırmıştır. Ya da bunu yapmadıysa, etkili gibi görünüyordu.

Bazı canavar UML modelleri gördüm ve açıkçası benim için kodun yapamayacağı hiçbir şey yapmıyorlar ve daha iyi yapıyorlar.