"Architecture.md (2021)" teknik spesifikasyon belgesi

ARCHITECTURE.md yazımı önerisi

• Açık kaynak proje bakımcılarına, README ve CONTRIBUTING yanında bir ARCHITECTURE belgesi eklemeleri güçlü biçimde tavsiye ediliyor.
• Bu belge, projenin yüksek seviyeli mimarisini açıklar ve düzenli katkı sunan kişilerin okuması gerektiği için kısa tutulması iyi olur.
• ARCHITECTURE belgesi yalnızca sık değişmeyen içerikleri kapsamalıdır; kodla senkron tutmaya çalışmak yerine yılda birkaç kez gözden geçirilmesi daha uygundur.

Belgenin amacı ve önemi

• Bir proje hakkındaki fiziksel mimari bilgisi, genel katkıcılarla çekirdek geliştiricileri ayıran en büyük farktır.
• Projeye aşina değilseniz bir yama yazmak 2 kat daha uzun sürer; kodu değiştirmek için doğru yeri bulmak ise 10 kat daha fazla zaman alır.
• ARCHITECTURE dosyası bu farkı kapatmanın etkili bir yoludur ve aynı zamanda projenin yapısı üzerine düşünme fırsatı sunar.

Belgenin yapısı

• Soruna yeni bir bakış açısından genel bir özetle başlamalı ve modüller arasındaki ilişkileri açıklayan ayrıntılı bir kod haritası sunmalıdır.
• Önemli dosyalar, modüller ve tipler belirtilmeli; ancak doğrudan bağlantı vermek yerine, bakım gerektirmemesi için adlarıyla aramaya teşvik edilmelidir.
• Mimari değişmezler açıkça işaret edilmeli ve katmanlar arasındaki sınırlar belirtilmelidir.

Mimari değişmezler ve sınırlar

• Önemli değişmezler çoğu zaman bir şeyin yokluğuyla ifade edilir ve bunu yalnızca kodu okuyarak fark etmek zordur.
• Katmanlar veya sistemler arasındaki sınırlar, sistemin uygulanışına dair bilgileri örtük olarak içerir ve mümkün olan tüm uygulamaları kısıtlar.

Uçtan uca ilgi alanları

• Kod haritası tamamlandıktan sonra, uçtan uca ilgi alanları için ayrı bir bölüm eklenmelidir.
• İyi bir ARCHITECTURE belgesi örneği olarak rust-analyzer'ın architecture.md dosyası verilebilir.

GN⁺ görüşü:

• ARCHITECTURE belgesi, projenin anlaşılmasına yardımcı olur ve yeni katkıcıların kod tabanına hızla alışmasında önemli bir rol oynar.
• Bu belge, projenin yapısını netleştirir ve önemli mimari ilkeler ile sınırları vurgulayarak geliştiricilerin sistemi daha iyi anlamasına yardımcı olur.
• Açık kaynak topluluğunda ARCHITECTURE belgesinin benimsenmesi, projenin sürdürülebilir büyümesine ve bakımına katkı sağlayabilir; bu da geliştiriciler için oldukça faydalı ve ilgi çekici bir yaklaşımdır.

[GN⁺]

Hacker News görüşleri

• Bir açık kaynak projeyi yönetiyor ve kod satırı sayısı 10k-200k arasındaysa, bir ARCHITECTURE belgesi eklemenizi şiddetle tavsiye ederim.

  • Fikir iyi, ama depo boyutundan bağımsız olarak mimariyi Readme'ye dahil edebileceğinizi düşünüyorum. Örneğin, tüm kullanıcıların iş akışını anlayabilmesi için ana Readme'ye bilinçli olarak Mermaid sıralama diyagramları yerleştiriyorum.

• Bu yaklaşım, çok sayıda ad hoc katkıcısı olan açık kaynak projeler için az bakım gerektiren bir model olarak harika. Özel mühendisleri olan projeler için ADR'ler düşünülmeli. Bunlar daha fazla bakım gerektirir, ancak "neden" ve "değerlendirilen alternatifleri" kaydettiği için yeniden inşa sırasında çok yardımcı olur.

• Birkaç yıl önce büyük yan projelerimden birinde benzer bir şeyi denedim:

  • Her dosyanın en üstünde, diğer ARCHITECTURE.md dosyalarına giden bir bağlantı ağacı vardı.

• Tüm IDE'ler solda projenin klasör yapısını standart bir dizin ağacı olarak gösteriyor. Bir projeyi bağımlılık grafiği üzerinden gezinmeyi destekleyen bir IDE var mı?

• Burada yazarın yazdıklarını genel yazılım projelerine genişletirken dikkatli olmak gerekiyor. Az bağlama sahip çok sayıda katkıcının bulunduğu büyük açık kaynak projelerinde bu tür belgeleri sürdürmek değerlidir. Ama küçük iş projelerinde, geliştiricilerin yazdığını gördüğüm tüm belgeler sonunda bakımsız kalıyor.

• Belge ne kadar kısa olursa, gelecekteki değişikliklerle geçersiz hale gelme olasılığı o kadar düşer. ARCHITECTURE belgesinin ana kuralı da budur — yalnızca sık değişmesi pek olası olmayan şeyleri belirtin. Kodla senkronize etmeye çalışmayın.

  • Arayüzlerin değişme olasılığı daha düşüktür ve [daha zordur!] (Parnas, sistemleri modüllere ayırmak için kullanılan ölçütler).

• Her projede işe alıştırma sırasında mimari diyagramı ve bileşenlerine dair kısa bir açıklama gösteriyorum.

  • Şimdi bunun açık kaynakta ne kadar nadir olduğuna şaşırıyorum.

• Bu çok faydalı bir pratik. Birçok projede değişikliklerin çoğunun gerçekleştiği birkaç çekirdek dosya (veya paket/modül/vb.) vardır. Yeni katkıcıların (ya da uzun süre sonra geri dönen katkıcıların) bunları hızla kavrayabilmesi, projeye başlama süresini ciddi biçimde kısaltabilir.

• Bu tür küçük belge/kod tabanlı diyagram standartlarının hayranıydım:

  • README güdümlü geliştirme
  • ARCHITECTURE.md
  • ADR'ler
  • arc42
  • C4
  • vesaire.
  • Artık git deposundaki /docs klasörünün içine bir Obsidian vault koyuyorum.
  • Bir başkasının standardını kullanmak yerine, belgeleri Obsidian'da kişisel notlarımı yönetir gibi düzenleyip yeniden yapılandırıyorum.
  • Hem GitHub(GFM) hem de Obsidian'da çalışan ortak bir Markdown alt kümesi kullanmaya çalıştım, ama sonunda vazgeçip Obsidian'ın Markdown'unu ve ona özgü özellikleri kullanmaya başladım.
  • Obsidian'da Mermaid ve LaTeX yerleşik geliyor, ayrıca PlantUML için bir eklenti var.
  • Görsel çizimler/diyagramlar için Canvas, DrawIO, Excalidraw yerleşik olarak mevcut.

• O sırada tartışıldı:

  • Architecture.md - Şub 2021 (153 yorum)