ARCHITECTURE.md (2021): Proje yapısı teknik şartnamesi

 (matklad.github.io)
1 puan yazan GN⁺ 2024-02-26 | 1 yorum | WhatsApp'ta paylaş
  • 10 bin~200 bin satır büyüklüğündeki açık kaynak projelerde README ve CONTRIBUTING yanında bir ARCHITECTURE belgesi bulundurmak, yeni katkıcıların kod yapısını kavrama maliyetini azaltabilir
  • Yabancı bir projede asıl sorun, yama yazmanın yaklaşık 2 kat yavaşlamasından çok, nereyi düzeltmek gerektiğini bulmanın 10 kat daha uzun sürmesidir
  • Bu belgenin üst düzey yapıyı ve sık değişmeyen içerikleri kısa biçimde içermesi; kodla sürekli senkronize edilmeye çalışılmasındansa yılda birkaç kez gözden geçirilmesi daha uygundur
  • Temel bileşenler, sorunun kuşbakışı görünümü ve kod haritası (codemap) olup büyük modülleri ve ilişkilerini göstererek “X’ten sorumlu kod nerede?” sorusuna yanıt vermelidir
  • Önemli adları, mimari değişmezleri, katman ve sistem sınırlarını, yatay kesen ilgi alanlarını kayda geçirmek; doğrudan bağlantılar yerine ada göre aramayı teşvik etmek bakım yükünü azaltır

ARCHITECTURE belgesinin azalttığı maliyet

  • Açık kaynak projelerde ara sıra katkı yapan kişilerle çekirdek geliştiriciler arasındaki en büyük fark, projenin fiziksel mimarisini bilip bilmemeleridir
  • Yabancı bir kod tabanında dosyalar, rastgele sıraya konmuş mantıksal parçalar gibi sırayla okunur
  • Daha önce anlamlı katkılar yapmış bir geliştiricinin zihninde bir kod haritası vardır; gerekli konuma doğrudan gider, yoksa ilgili kodu oraya taşıyabilir
  • ARCHITECTURE dosyası, bu farkı düşük maliyetle azaltmanın bir yoludur
  • Belge kısa olmalıdır
    • Çünkü tekrar tekrar katkı yapan herkesin onu okuması gerekir
    • Ne kadar kısa olursa gelecekteki değişikliklerle geçersiz hale gelme olasılığı o kadar düşük olur
  • ARCHITECTURE için ölçüt, sık değişmeyecek içerikleri barındırmasıdır
    • Kodla sürekli senkronize etmeye çalışmayın
    • Bunun yerine yılda birkaç kez yeniden gözden geçirin

Neler içermeli?

  • Önce projenin çözdüğü problemi kuşbakışı düzeyde özetleyin
  • Ardından belirli bir ayrıntı düzeyinde kod haritası (codemap) hazırlayın
    • Büyük ölçekli modülleri ve birbirleriyle ilişkilerini açıklayın
    • “X’i yapan şey nerede?” sorusuna yanıt vermelidir
    • “Şu anda baktığım bu şey ne yapıyor?” sorusuna da yanıt vermelidir
  • Her modülün iç işleyişine kadar derine inmeyin
    • Bu tür içerikler ayrı bir belgeye ya da daha iyisi satır içi dokümantasyona taşınmalıdır
    • Kod haritası bir ülke haritasıdır, eyalet eyalet bir atlas değildir
  • Kod haritası yazılırken proje yapısı da birlikte gözden geçirilebilir
    • Kod haritasında birbirine yakın olmasını istediğiniz şeylerin tree . çıktısında da bitişik olup olmadığını kontrol edebilirsiniz
  • Önemli dosya, modül ve tip adlarını açıkça belirtin
    • Doğrudan bağlantılardan kaçının; zamanla kırılabilirler
    • Bunun yerine sembolleri ada göre aramaya yönlendirmek, bakım yükü oluşturmadan ilgili benzer adlı öğelerin de bulunmasını sağlayabilir
  • Mimari değişmezler açıkça yazılmalıdır
    • Önemli değişmezler çoğu zaman bir şeyin “olmadığı” biçiminde ortaya çıkar
    • Örneğin web geliştirmede model katmanının view’a bağımlı olmadığı gerçeğini yalnızca kodu okuyarak çıkarmak zor olabilir
  • Katmanlar ve sistemler arasındaki sınırlar da gösterilmelidir
    • Sınır, arkasındaki sistem uygulamasına dair bilgiyi ima eder
    • Olası tüm uygulamaları da kısıtlar
    • İyi bir sınırı kod içinde rastgele bulmak zor olduğundan dokümante etmek faydalıdır
  • Kod haritasından sonra yatay kesen ilgi alanları için ayrı bir bölüm ekleyin
  • Başvurulabilecek örnekler rust-analyzer’ın architecture.md dosyasında görülebilir

İlgili okumalar

1 yorum

 
GN⁺ 2024-02-26
Hacker News yorumları

  • Bu fikri beğeniyorum; depo boyutundan bağımsız olarak mimari açıklaması için README’de de yer olduğunu düşünüyorum.
    Örneğin, tüm okuyucuların iş akışını görüp anlamasının önemli olduğunu düşündüğüm için ana README’ye özellikle bir Mermaid sequence diagram[1] koydum[2].
    [1] https://mermaid.js.org/syntax/sequenceDiagram.html
    [2] https://github.com/hbcondo/revenut-app?tab=readme-ov-file#-w...

    • Doğal dilden Mermaid diyagramları üreten bir araç olsa oldukça güzel olurdu. Üzerinde düşünmeye değer.

  • Kulağa gerçekten iyi bir tavsiye gibi geliyor.
    Çalışan bir sistemin mimarisini görselleştiren araçların daha iyi olmasını isterdim. Hâlâ kod okumak ya da Markdown dosyalarına bakmak en güncel yöntemmiş gibi olması tuhaf. Şanslıysanız belki bir Mermaid diyagramı vardır.
    Mimarinin kendini gerçek zamanlı olarak ortaya koymasını isterdim. Makro ölçekte gözlemlenebilirliğin varsayılan olarak yerleşik olduğu bir şey güzel olurdu; bunun herkesin bilişimi daha iyi anlamasına ve insanlığın kendini artırmasına da yardımcı olacağını düşünüyorum.

    • dep-tree gibi görselleştirmelere anahtar kelime araması veya LLM vektör araması eklemek iyi olurdu. Sorgu yapınca ilgili dosyaların ve kümelerin vurgulanması gibi.

  • Geçici katkıcısı çok olan açık kaynak projeleri için az bakım gerektiren bir model olarak iyi görünüyor. Adanmış mühendisleri olan projelerde ADR de düşünülmeye değer.
    ADR daha fazla bakım gerektirir ama “neden böyle yapıldı” ve “değerlendirilen alternatifler” bilgisini bıraktığı için yeniden tasarım sırasında çok faydalıdır.
    Referans: https://adr.github.io/

    • Burada “yerine”den çok “birlikte” demek daha doğru gibi.
      ARCHITECTURE.md mevcut mimari durumunu içerir; ADR ise oraya gelinmesini sağlayan kararların kaydıdır. İkisi de çok faydalıdır.
    • Bizim şirkette de mimarların yazdığı işe yaramaz belgeler var; çoğu bu tarzda.
      Microservices, Kafka, Kubernetes: Şu an 4 bin kullanıcımız var ama ya 1 milyar olursa diye.
      GraphDB: Ya SQL yeterli olmazsa diye.
      ElasticSearch: Ya istatistiklerin yanında full-text search de yapmamız gerekirse diye.
      Ama bu belgelerin çoğu sonunda “eğlenceli olduğu için yeni bir mimari/teknoloji denemek istiyorum, FAANG’de çalışan iş arkadaşım kullanıyor, o kitabı okudum, özgeçmişte iyi görünür”ün kısaltması oluyor.
      Onlar bir sonraki büyük proje tasarımına geçtikten sonra, bizim ekip ekip üyesi sayısından fazla servisi ve yukarıdaki veritabanları/teknolojileri sürekli senkronize tutmak zorunda kalıyor. Tabii bu tür sorunlar “büyük mimari kararlar” almaktan çok daha basitmiş gibi görülüyor.

  • Aklıma geldi: Kullandığım tüm IDE’ler solda proje klasör yapısını standart bir dizin ağacı olarak gösteriyor. Projeyi bağımlılık grafiği üzerinden gezdirmeye izin veren bir IDE var mı?

    • Sorunun doğrudan cevabı değil ama sonuçta “dosya yapısını daha iyi görselleştirmek istiyorum” demek gibi görünüyor.
      İçindekiler tablosu tarzı gösterimin pek uymadığını düşünüyorum. Güncel kodlama iş akışımda terminali açıp içinde ranger çalıştırıyorum; soldan sağa dizin yapısını gezerken o terminale sekme değiştiriyorum. VSCode’u açıp bölünmüş terminalde üstte normal terminal, altta Ranger çalıştırmak gibi. Midnight Commander da olur; aslında bir TUI dosya gezgini yeterli.
      Ayrıca projenin architecture.md dosyasına kod haritası eklemeye başladım. tree -L çalıştırınca Markdown’a koymaya uygun dosya yapısı ağaç diyagramını istediğiniz derinlikte alabilirsiniz. Bu çıktıyı Markdown’a ekliyor, her dosya/klasörün arkasına da 10 kelimeden kısa, amacını açıklayan bir not koyuyorum.
      Ranger - https://github.com/ranger/ranger
      Midnight Commander - https://midnight-commander.org/
    • Ben de tam olarak aynı şeyi düşündüm.
      Nasıl görünebileceğine dair iki fikrim var.
      Birincisi, sembolik bağlantılar kullanarak dosyaları ortogonal biçimde organize eden birden fazla dizin ağacı. Normal dizin yapısı client/server diye ayrılır; peki özelliklere göre ayırmak istersek? IDE bunu çok daha kolay oluşturabilir.
      İkincisi, bu yazının yönüne benzer şekilde IDE’nin yer imleri oluşturup aralarında gidip gelmeyi ve insanlara kodu anlatmayı kolaylaştırmasını isterdim. Bazen yorum bırakıp tıklayınca kod tabanının başka bir yerine atlamak istiyorum. Bunları birbirine bağlayınca, kod tabanının tamamında nasıl çalıştığını açıklayan bir anlatı örülebilir.
      Bu yönde çalışan biri var mı merak ediyorum.
    • Pratikte nasıl görünür? Örneğin döngüsel bağımlılıklar nasıl ele alınabilir?
    • Belki de istediğiniz şey multitree olabilir.

  • Burada yazarın söylediklerini genel yazılım projelerine fazla genişletirken dikkatli olmak gerektiğini düşünüyorum.
    Bağlamı az olan çok sayıda katkıcının bulunduğu büyük açık kaynak projelerinde böyle bir belgeyi sürdürmek çok değerlidir. Ama küçük iş projelerinde geliştiricilerin commit ettiği belgelerin sonunda hepsinin bakımsız kaldığını gördüm.

    • Ekiplerle birkaç kez mimari oturumu yaptım ve her zaman değerli oldu.
      En azından ekip üyelerinin mevcut mimari ve ideal mimari hakkında birbirinden çok farklı fikirlere sahip olduğunu öğrendik. Bunu açıkça ortaya koymak bile belge oluşturmaya değer.
      Ayrıca “belgeler bakımsız kalır” argümanı, belge oluşturmamak için çok zayıf bir gerekçe. Çünkü eski ya da incelikli biçimde yanlış da olsa herhangi bir belge, “hiç belge olmamasından” iyidir.

  • Birkaç yıl önce büyük yan projelerimden birinde benzer bir yaklaşımı denemiştim
    https://github.com/shipmight/shipmight/blob/master/src/ARCHI...
    Her dosyanın üst kısmına depodaki diğer ARCHITECTURE.md dosyalarına giden bir bağlantı ağacı koymuştum. Örnek şöyle: ARCHITECTURE.md <- mevcut konum, 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

  • Ne kadar kısa olursa, gelecekteki değişikliklerle geçersiz hâle gelme olasılığı o kadar düşük olur. ARCHITECTURE için temel pratik kural, yalnızca sık değişmeyecek şeyleri yazmaktır. Kodla senkron tutmaya çalışmamak gerekir
    Arayüzlerin değişme olasılığı daha düşüktür ve değiştirilmeleri de daha zordur. Bu, bir sistemi modüllere ayırırken kullanılan ölçütlere dair Parnas’ın bakış açısıdır
    Kod tabanını anlamanın zor olduğuna katılıyorum. “Pattern” adları vermek bir ölçüde yardımcı olsa da sonunda epey okuma yapmak gerekiyor
    GitHub’da dosya bazındaki commit mesajları çoğu zaman açıklama gibi hissettiriyor. Acaba bu daha faydalı olabilir mi?

  • Dahil olduğum tüm projelerde onboarding sırasında mimari diyagramı ve bileşenlere dair kısa bir açıklama almıştım
    Bu yüzden açık kaynakta bunun bu kadar yaygın olmaması şaşırtıcı

    • “Bileşen açıklaması” tam da sorun olan kısım. Çünkü bunu birinin yapması gerekiyor
      Açık kaynak projelerde bir çalışanın ilk iş günü olmadığı için böyle bir tanıtım da yok
      Çok fazla zamanınız yoksa bu tür açıklamalar pek iyi olmuyor. Bir çalışanın tek başına bir şeyler çıkarabilmesi için birkaç hafta geçmesi beklenir; ama güvenlik danışmanları olarak biz her 2 haftada bir tamamen yeni bir açıklama dinliyoruz. Sorun, bu açıklamaların doğaçlama ve yapılandırılmamış olması, anlatan kişinin de bilgi laneti yüzünden alakasız pek çok ayrıntıdan bahsetmesi
      Muhtemelen depoya yeni gelen birinin bunu bir kez yazması, sonrasında da yalnızca bakımının yapılması iyi olur. İkinci en iyi seçenek ise herhangi birinin her seferinde doğaçlama anlatması yerine, neyi dahil edip neyi dışarıda bırakacağını yaklaşık 1 dakika düşünüp yazıya dökmesidir. Yazarın da söylediği gibi bu dosya projenin üst düzey mimarisini açıklamalı ve kısa olmalı. Düzenli katkı veren herkes bunu okumalı; ayrıca ne kadar kısa olursa gelecekteki değişikliklerle geçersiz hâle gelme olasılığı da o kadar düşük olur

  • Bunun her zaman çok faydalı bir pratik olduğunu düşündüm. Birçok projede değişikliklerin çoğunun gerçekleştiği birkaç çekirdek dosya ya da paket/modül vb. vardır
    Yeni katkı verenler veya uzun bir aradan sonra dönen katkı verenler bunları hızlıca kavrayabilirse projeye başlama süresi ciddi biçimde azalır
    Birkaç iş yerinde projelere mimari dosyası ekledim ve [0], [1] tepkiler olumluydu. Mükemmel değil ama hiç olmamasından iyidir
    [0]: https://github.com/zapier/zapier-platform/pull/324
    [1]: https://github.com/stripe/stripe-cli/blob/master/ARCHITECTUR...

    • GitHub’da böyle bir şeyi otomatik görmenin bir yolu var mı? Örneğin dosya değişikliği ısı haritası gibi

  • Eskiden bu küçük dokümantasyon/diyagram-as-code standartlarını severdim
    README odaklı geliştirme, ARCHITECTURE.md, ADR, arc42, C4 vb.
    Şimdi ise git deposundaki /docs klasörüne bir Obsidian kasası koyuyorum
    Başkalarının standartlarını kullanmak yerine, Obsidian’da kişisel notları yönetir gibi dokümanları sürekli düzenleyip refactor ediyorum
    Başta GitHub’ın GFM’i ile Obsidian’ın ikisinde de çalışan ortak bir Markdown alt kümesi kullanmak istemiştim ama vazgeçtim; artık Dataview eklentisi ve şablonlar gibi kendine özgü özellikler dahil, Obsidian tarzı Markdown’ı olduğu gibi kullanıyorum
    Mermaid ve LaTeX Obsidian’da yerleşik geliyor, PlantUML eklentisi de var. Görsel çizimler/diyagramlar için yerleşik Canvas, DrawIO ve Excalidraw kullanıyorum