Yazılım mimarisi diyagramları nasıl çizilir (2022)

 (terrastruct.com)
3 puan yazan GN⁺ 2023-10-28 | 1 yorum | WhatsApp'ta paylaş
  • İyi bir mimari diyagramı, süsten çok doğru soyutlama düzeyi, güncellik ve belirsizliğin giderilmesi sayesinde fikir aktarımının ve iş birliğinin uzun süre sürmesini sağlar
  • Bağlantılı öğeleri birbirine yakın tutan komşu mesafesini en aza indirme temel ilkedir; diyagram büyüdükçe silip yeniden çizme yinelemeleri gerekebilir
  • Simetri yalnızca hoş bir izlenim yaratmakla kalmaz; girdileri ve çıktıları farklı taraflara yerleştirmek gibi yöntemlerle anlam aktarımını da güçlendirir
  • Şekillerin merkez hizalamasını korumak, karmaşık kavramların bile daha az karmaşık görünmesini sağlar ve yeni öğeler eklendiğinde genel yerleşimin bozulmasını önler
  • Etiketli kapsayıcı gruplar, AWS ve Azure gibi ortam ayrımlarını, ReaderWriter implementasyonları gibi soyutlamaları ve Cores gibi ilişkili nesne kümelerini tek bakışta gösterir

Kalıcı diyagramların koşulları

  • İyi bir diyagram, toplantı bittikten sonra da silinmez; sonraki tartışmalar ve sorular için referans noktası olarak kullanılmaya devam edebilir
  • Uzun süre kullanılan diyagramlarda birkaç ortak koşul vardır
    • Öğeler doğru soyutlama düzeyinde olmalıdır
    • Güncel tutulmalıdır
    • Belirsizlik içermemelidir
  • Aynı varlıklar ve ilişkiler birçok farklı şekilde çizilebilir; ancak bazı yerleşimler proje süresince iş birliğine yardımcı olurken bazıları toplantı biter bitmez ortadan kaybolur
  • Burada sözü edilen güzellik, gölge veya yuvarlatılmış köşeler gibi süslemeler değil; düşünceleri etkili biçimde aktaran işlevsel güzelliktir

Okunması kolay bir yerleşim oluşturma ilkeleri

  • Komşu mesafesini en aza indirme

    • Birbirine bağlı düğümleri yakın çizmek temel kuraldır
    • Küçük diyagramlarda bu kolaydır, ancak diyagram büyüyüp yeni bağlantılar eklendikçe bu özelliğin bozulması kolaylaşır
    • Kodda bir edge case bulduğunuzda ilgili kısmı düzeltmeniz, belgede eksik bir madde bulduğunuzda cümleyi düzenlemeniz gibi, dokümantasyon amaçlı diyagramlar da gerekiyorsa silinip yeniden çizilmelidir
    • Mülakat durumlarında yeniden çizmenin maliyeti yük gibi gelebilir; ancak birden fazla kişinin veya birden fazla ekibin kullanacağı bir dokümansa, yinelemeli düzenleme daha iyi bir diyagrama götürür

  • Simetri arama

    • Simetri, diyagramın estetik izlenimine büyük katkı sağlar; insan beyni, yüzlerde olduğu gibi görsel simetriyi tercih etme eğilimindedir
    • Tüm düğümler komşularına olabildiğince yakın olsa bile simetri eksikse, çizim biraz yamuk görünmüş gibi algılanabilir
    • Bir düğümün komşu mesafesi biraz artsa bile, simetrisi ayarlanmış sürüm daha hoş görünebilir
    • Girdileri bir tarafa, çıktıları diğer tarafa koyma yöntemi, simetriyle birlikte diyagramın anlamını da güçlendirir

  • Merkez hizalama

    • Hizalama, diyagramın düzenli görünmesini sağlayan önemli bir unsurdur
    • Düzenli bir diyagram kavramı daha net hale getirir; dağınık bir diyagram ise kavramı daha karmaşık gösterir
    • En baştan boş bir tuvale şekilleri rastgele yerleştirirseniz, sonraki yerleşimlerin de rastgele kalması kolaydır
    • Hizalama yalnızca iki veya daha fazla şekil arasında anlamlı olduğundan, her yeni öğe eklendiğinde hizalamayı korumak diyagramın doğal olarak düzenli kalmasını sağlar
    • Simetri çoğu zaman hizalama doğurur, ancak bu her zaman böyle değildir

  • Kapsayıcı gruplar kullanma

    • Diyagramı etiketli birden fazla alana ayırmak, izleyenin yapıyı daha kolay anlamasını sağlar
    • Kapsayıcılar diyagrama şu bilgileri ekleyebilir
      • “Bu servisler AWS’te, bu servisler Azure’da” örneğinde olduğu gibi bağlam ekler
      • “Bunların hepsi ReaderWriter’ın implementasyonlarıdır” örneğinde olduğu gibi soyutlamayı gösterir
      • core 1, 2, 3, 4’ü “Cores” kapsayıcısında toplamak gibi ilişkili nesneleri gruplar

Sonraki bölümde devam eden konular

  • Part 2’de şu konular devam eder
    • Edge rotaları çizme
    • Etiket boyutu ve konumu
    • Renk
    • İkonlar

İlgili okumalar

1 yorum

 
GN⁺ 2023-10-28
Hacker News yorumları

  • Diyagram oluşturmak için D2 kullanmayı seviyorum. mermaid.js’ye benziyor ama daha fazla biçimlendirme seçeneği var; kişisel olarak sözdizimini de daha iyi buluyorum
    Bununla ilgili kısa bir yazı da yazdım: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Diyagramların güzel olmaması gerektiğini düşünüyorum. Örneğin renkler estetik/sanatsal bir tercih için değil, anlam aktarmak için kullanılmalı
      Çirkin yazılım diyagramlarına bakmanın keyifli olmadığını biliyorum ama süslemek, çizgi grafiğe eğriler eklemek gibi. Görsel olarak iyi görünse de aktarmaya çalıştığınız veriyi engeller
    • Örneği takip ettim ve gerçekten harikaydı, ama yönergenin aksine soldan sağa değil yukarıdan aşağıya render edildi
      İlk örnek olan x -> y’yi SVG olarak render edip yalnızca SVG’yi tarayıcıda açtım; çıktının hizalanma yöntemini tüm dokümantasyonda aradım ama bulamadım
      Dokümantasyon ile gerçek sonuç farklı olduğu için kullanmayı bıraktım. "d2lang connection left to right" diye aratınca https://d2lang.com/tour/layouts/ sayfasına ulaştım; genel bakış dokümanında bağlantılı görünmüyor, eklerseniz ziyaretçilere faydalı olabilir
    • https://flowchart.fun/ sistem süreçlerini anlamak için akış şemalarını çok hızlı çizmeme yardımcı oldu. En sevdiğim yanı sezgisel olması ve hızlı yineleme yapılabilmesiydi; stil için özel CSS de oldukça kullanışlıydı
      Akış şemaları özelinde, şimdiye kadar kullandığım metin tabanlı diyagram araçları arasında en kolay ve en hızlı olanlardan biri olduğunu düşünüyorum
    • D2’de çok iyi bir yerleşim motoru olan tala var, ancak kullanmak için ücretli lisans gerekiyor. Diğer iki motor onun kadar iyi değil
    • mermaid’i seviyorum ve sık kullanıyorum; D2’ye de bakmam gerekecek. Deklaratif diyagramların, düşünceleri okunabilir bir biçimde yakalayan ve diğer metinler gibi sürüm kontrolüne alınabilmelerini sağlayan güçlü bir araç olduğunu düşünüyorum

  • Sistem değişmeye başladığında güzel diyagramları korumak çok zorlaşıyor. Zaten karmaşık bir diyagramın ortasına yeni bir kutu eklediğinizi düşünün; her şeyi yeniden hizalamak bir saatinizi alabilir
    2020’lerde geliştirici zamanını diyagramları kod olarak yönetmeye harcamak muhtemelen daha iyi: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Diyagram hazırlamanın %10’u gerçek diyagramı yapmak, %90’ı ise okları hizalamaktır diye hep şaka yaparım
      Ama aslında şaka değil gibi
    • structurizr.com’a içe aktarıp göstermek için bir C4 modeli tutuyordum; dürüst olmak gerekirse keyifli değildi. Sadece koddan, diyagramın sağladığı sezgisel anlama ve genel bakış çıkmıyordu; hızlı bir yerel önizleme de olmadığı için kodu sunucuya yüklemek gerekiyordu
      Daha da kötüsü, yeni bir kutu eklediğinizde genellikle tüm okları yeniden hizalamanız gerekiyordu. Sonuç olarak diyagramlar sürekli güncel kalmadı
      Sıralama diyagramlarında plantML kullandığımda daha iyiydi. İşin kendisi daha kolaydı; bu yüzden yorumlayıcı çıktısı genelde elle müdahale gerektirmeden kullanılabilir oluyordu
    • Yazıda da diyagramları değiştirmenin çok zaman aldığı ele alınıyor. Gerçekten de öyle; standartlaştırılmış bir şemayı düzgünce takip edebilsek ve araç otomatik biçimlendirme seçenekleri sunsa iyi olurdu
    • Öğeleri taşıyıp yeniden hizaladığınızda tüm diyagramı yeniden öğrenmeniz gerekir. frobnitz hep sağ üstte dururken, hizalama açısından daha iyi diye bir anda sol ortaya taşınırsa, ilk kez gören biri için yardımcı olabilir ama 6 aydır ona bakan biri için bambaşka bir şey gibi görünür
      Çirkin UI’a benzer. Çirkin olsa da kullanıcıları ona zaten alışmıştır. “Düzenlediğiniz” anda onların zihinsel modelini bozup yeniden öğrenmeye zorlarsınız
    • Bu zaman yatırımının değip değmeyeceği diyagramın erişim alanına ve ömrüne bağlıdır
      Bazen yalnızca düşünceleri toparlamak için 20 dakika sonra atılacak bir eskiz yaparsınız
      Ama onboarding için ya da sistemi başka bir ekibe açıklayan bir referans materyali olarak kullanılacaksa, daha anlaşılır bir şey üretmeye harcanan bir saat fazlasıyla karşılığını verebilir

  • Böyle şeyler çizerken yEd kullanıyorum. Kutuları ve okları karmakarışık yapsanız bile menüden birkaç tıklamayla otomatik düzenliyor
    Yine de taviz vermek gerekiyor. Kutuların içindeki kutular her zaman iyi sonuçlanmıyor. Buna rağmen çok daha hızlı dokümantasyon yapabiliyorum; birkaç kez denedikten sonra neyin işe yarayıp neyin yaramadığına dair sezgi gelişiyor, bu yüzden benim için makul bir ödün

    • yEd’in ücretsiz kullanılıp kullanılamadığını merak ediyorum. Temelindeki yWorks SDK, tek bir web sitesinde tek bir geliştiricinin kullanması için bile 5 haneli bir tutara mal oluyor gibi. Yaklaşık 20 yıldır müşterileri varsa oldukça güçlü bir araç olmalı
    • Ben de aynısını kullanıyorum. Elle çizmek için bir sebep yok
      İlişkileri TGF olarak çıkarıp içe aktarın, ardından hiyerarşik yerleşimi uygulayın
      from, to, relation biçimi yeterli
    • Benzer nedenlerle OmniGraffle kullanıyorum

  • Bunun elektrik şemaları, devre diyagramları ve diğer mühendislik çizimleriyle güçlü benzerlikleri var. Tek bir “doğru” yöntem yok
    Kodda olduğu gibi, iyi soyutlama ve temsil biçimleri seçebilmek; anlaşılabilir fikirlerle pişmanlık verici bir karmaşa arasındaki farkı belirler. Bu güzellik ya da estetik meselesi değil; tasarıma aktif düşünce ve emek gerektiren bir araçtır

    • Soyutlama seviyesini tutarlı tutmak bazen gerçekten zor. Özellikle altyapı diyagramlarında, farklı ayrıntı seviyelerinden daha fazlasını ekleme dürtüsünü durdurmak zor oluyor
      Sonsuz yakınlaştırma animasyonu gibi diyagramın içine kolayca yakınlaşmayı sağlayan bir araç olsa güzel olurdu

  • Yakında https://VisualFlows.io v1.0’ı yayımlamayı planlıyoruz
    Ana şirketimizin SaaS’ı için birkaç dakika içinde animasyonlu bir “mimari” haritası oluşturabildim: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Başlıca özellikler Smart Sections, Smart Edges, Smart Node Deletion, koyu/açık mod, embed, görsel/SVG/GIF sürükle-bırak, AWS/Windows/Google ikonları ve gelecek hafta planlanan Markdown vb.
    Smart Sections için bkz.: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Aynı estetiğe sahip, daha olgun https://whimsical.com yerine bunu kullanmak için sebebin ne olduğunu merak ediyorum

  • Bu yazıyı gerçekten çok beğendim. Mimari diyagramı çizerken, doküman ya da kod yazarken, işte bir şey yaparken kısa bir zaman ayırıp onu “güzel görünecek” hale getirmeye çalışıyorum
    Nedenini açıklamak zor, ama baktıktan sonra daha çok içime sindiğini biliyorum
    Bunun zamanı en iyi kullanma biçimi olmayabileceğinden biraz endişe ediyordum, ama kimse bana yapma demedi
    Bu yazının iyi yanı, sezgisel olarak yaptığım şeyi bir şeyi daha güzel hale getirmenin pratik bir yolu olarak açıklaması

    • Ben de böyle yapıyorum. Kodlama benim için oldukça görsel bir iş. Bunu ancak “akış” diye tarif edebiliyorum. Kodda akış yoksa tatmin edici gelmiyor
      Kodun görsel hissine sahip değilmiş gibi görünen ekip arkadaşlarını görünce şaşırıyorum. Bir fonksiyonun sonuyla sonraki fonksiyon bildirimi arasına boşluk koymamaları ya da fonksiyon imzasında parametreleri bazen satır başına bir tane, bazen birkaç tane olacak şekilde tutarsız yazmaları gibi. Benim gözüme çok batıyor, ama onlar umursamıyor gibi
    • Kimseyle paylaşmayacak olsanız bile, sayfadaki blokların ve öğelerin sırasını düşünme sürecinin kendisi daha büyük yapıyı ve bağımlılıkları düşündürüyor. Müthiş yardımcı oluyor
    • Visio ile ağ diyagramı hazırlarken de aynı hissi alıyorum. Steve Jobs moduna girip küçük detaylara takılıyorum
      Bazen zaman alıyor ama insana bir şeylerin tamamlandığı hissini veriyor. Bir ölçüde teknik sanat yeteneğim olduğunu biliyorum ve lisede teknik ressam olmak istemiştim
    • İşte markup bu yüzden var. Verimsiz süslemeden uzaklaşmanızı sağlıyor. Tabii kodlama için geçerli değil
    • “Tartışma bu diyagramın etrafında döner. İnsanlar farkında olmadan yaklaşıp ona bakar. Sorular, diyagram işaret edilerek yanıtlanır. Gün içinde sandalyeler periyodik olarak bu merkez parçaya doğru döner ve insanlar ellerini başlarının arkasında kenetler.”
      Görselleştirmenin hedefinin ta kendisi

  • Bu amaç için D2 iyi. Önceki rolümde tüm serverless.yml dosyalarını ayrıştırıp devasa bir D2 diyagramını otomatik üreten bir program yazmıştım
    AWS üzerinde mikroservisler yapıyorduk ve sistem büyüdükçe otomatik güncellenmesi güzeldi. SNS topic’lerine göre ayırmak gibi yöntemlerle her alt sistem için daha küçük diyagramlara bölebilecek şekilde tasarlamıştım

    • draw.io’yu da seviyorum

  • İlk örneği anlamadım. Yazar planlanmamış bir node’dan bahsederken gerçekten “I was unplanned” diye adlandırıyor, sonra da “önceden planlamış olsaydım” diyor
    Diyagram bağlamında planlanmamış bir şeyi nasıl önceden planlayabileceğinizi bilmiyorum. Acaba tüm node’ların etrafında yeterince boşluk bırakmak gerektiğini mi kastediyor?
    Ayrıca önerilen iyileştirme, “something” ile “I was unplanned”ın “engine” ile etkileşirken aynı kanalı ya da mekanizmayı kullanıyormuş gibi görünmesine yol açıyor

  • Miro kullanıyorum; yüksek seviyeli içerikler ya da fikir geliştirme için post-it aracıyla gayet iyi. Ancak orta seviyenin ötesine geçmiyor
    Bileşenler ve sistemler netleştikten sonra o işe daha uygun araçlar var

  • Proje dokümantasyonu Markdown ise, ayrı bir binary yerine diyagram eklemek için ```plantuml blokları koyabilirsiniz
    GitLab’de .md dosyalarını tarayıcıda görüntülerken güzel biçimde render ediliyor. GitHub’da bu özellik henüz yok