Neden ADR yazmalısınız

ADR = Architecture Decision Records

Mimari kararların neden o şekilde alındığını kod tabanının içinde kaydetmek.
GitHub bunu iOS/Android mobil ekibinde uyguluyor ve neden gerekli olduğunu anlatan bir yazı.

Sizin için değil, gelecekteki siz için

ADR, verdiğim karara dair bir öz değerlendirme süreci değil; bundan 6–12 ay sonra bu mimariyi seçtiğimiz andaki düşünce yapısını hatırlamaya yardımcı olur.
ADR, kararın alındığı anı yakalar ve toplantı/Zoom görüşmesi/Slack/kod içinde ele alınan PoC'leri de kapsar.
Amaç, zihninizdeki bu bağlamı kelimelere dökerek ileride bu mimariye yeniden baktığınızda aynı bağlamı tekrar zihninize yerleştirebilmektir.

Asıl bonus, birkaç ay sonra birisi GitHubAPIClient modülünün neden böyle çalıştığını sizi suçlayarak sorduğunda ortaya çıkar.
Kodu açıklamak için 30 dakika pair programming yapmak yerine, bu ADR'yi verip o modül oluşturulurken alınan kararları açıklayabilirsiniz.

Sizin için değil, ekip arkadaşlarınız için

ADR, tek satırlık "bu özellik feature-#3128'in implementasyonudur" açıklamasından daha fazlasını yazmalıdır.
Ekip arkadaşlarının bu özelliğin neden başka bir şekilde değil de bu şekilde yapıldığını anlamasına yardımcı olan daha kapsamlı bir açıklama biçimidir.
(ADR içinde "değerlendirilen alternatifler", "artılar ve eksiler" gibi başlıklarla ifade edilebilir.)

Size basit gelen bir şey, ekip arkadaşlarınız için karmaşık olabilir.
Biraz zaman ayırıp karar verirken düşündüğünüz süreci yazarsanız, ekip üyelerine zihninizin içine girme fırsatı vermiş olursunuz.
ADR yazmak, "Decision Socialization"ı (kararların ekip içinde paylaşılması) mümkün kılar.
Böylece bireysel olarak karar vermek yerine, ekibin bakım sorumluluğunu üstleneceği kararlar alınmasını sağlar.

Pull request açmadan önce ADR yazarsanız, bunu inceleyen ekipten daha iyi PR review alabilirsiniz.

Sizin için değil, gelecekteki ekip arkadaşlarınız için

ADR, ne kadar zeki olduğunuzu göstermek ya da insanların kurduğunuz mimariye bakıp afallamasını sağlamak için değildir.
ADR, yeni bir ekip üyesi katıldığında onun mevcut kod tabanını ve kod tabanının zaman içinde nasıl evrildiğini anlamasına yardımcı olur.

Ekip genişleyip büyüdükçe ekip üyeleri arasındaki iletişim yolları artar.
Bu şekilde alınan kararları yazıya dökmek, ekip büyürken yeni katılan kişilerle de iletişim kurmayı kolaylaştırır.

En iyi senaryo, ekip arkadaşlarınızdan birinin yeni bir ADR yazarak sizin geçmişte verdiğiniz kararı değiştirmesi ve gelecekte sizin de ekip arkadaşlarınızdan öğrenebilmenizdir.

"Daha fazla ADR yazın. Ekibimiz büyüdükçe ve kod tabanımız karmaşıklaştıkça ADR'ler, gelecekteki bize, mevcut ekip üyelerine ve gelecekteki ekip üyelerine yardımcı olmanın harika bir yoludur."

[xguru]

E-devlet örnekleri arasında ünlü olan Gov.UK’nin, kendi AWS bulut mimarisiyle ilgili ADR’lerini düzenlediği bir repository de var.

https://github.com/alphagov/govuk-aws/…

[beatblue]

İyi bir referans oldu.

[xguru]

ADR örnekleri

CSS framework kararı

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Sorun: Web uygulaması için bir CSS framework’üne karar verilmesi gerekiyor. Tanınmış tarayıcılar ve ekran boyutlarından bağımsız olarak hızlı ve kararlı olmalı. Tasarım/layout/UI/UX tarafında hızlı iterasyon. Responsive tasarım

• Karar: Bulma kullanılmasına karar verildi

• Varsayım: Modern, hızlı ve responsive bir web uygulaması yapmak istediğimiz için jQuery kullanmak istemiyoruz

• Kısıt: jQuery kullanmayı gerektirmeyen bir framework olmalı

• Değerlendirilenler: Hiçbir şey kullanmamak ya da Bootstrap/Bulma/Foundation/Materialize/Semantic UI arasından seçim yapmak; özellikle Bulma ve Semantic UI derinlemesine değerlendirildi

Monorepo vs Multirepo

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Sorun: Projemizin üç ana kategorisi var - frontend UI, middleware, backend sunucusu

→ SCM olarak git kullanıyoruz; bu yüzden monorepo vs polyrepo vs hybrid arasında karar vermemiz gerekiyor

• Karar:

→ Organizasyon/ekip/proje küçükse ve hızlı iterasyon gerekiyorsa Monorepo

→ Organizasyon/ekip/proje büyükse ve istikrar önemliyse Polyrepo

• Varsayım: Yazdığımız kod organizasyon içindir, dışarıya (kamusal kullanıma) yönelik değildir

Programlama dili kararı

https://github.com/joelparkerhenderson/architecture_decision_record/…

• Sorun: Yazılım geliştirme için kullanılacak dillere karar verilmesi gerekiyor. Web frontend ve backend

• Karar:

→ Frontend için TypeScript

→ Backend için Rust

• Varsayım:

→ Frontend tarafı genel amaçlı olmalı ama hızlı geliştirme, dağıtım ve yineleme mümkün olmalı. Legacy uyumluluğu gerekmiyor

→ Backend tarafında genel çözümlerin biraz üstünde gereksinimler var. Kalite, kararlılık ve güvenlik önemli. Neredeyse gerçek zamanlı düzey gerekli (GC nedeniyle duraksamalar olmamalı). Fonksiyonel programlama / paralel işlem ve çok çekirdekli işleme ile bellek güvenliği de önemli

• Kısıt: Büyük bulut servislerinin serverless hizmetlerinde (Amazon Lamba) mutlaka çalışabilmeli

• Değerlendirilenler: C/C++/Clojure/Elixir/Erlang/Elm/Flow/Go/Haskell/Java/Javascript/Kotlin/Python/Ruby/Rust/TypeScript

• Tartışmalar:

→ C: Düşük güvenlik nedeniyle elendi; Rust çoğu şeyi daha iyi yapabiliyor

→ C++: Dağınık/mess olduğu için elendi; Rust çoğu şeyi daha iyi yapabiliyor

→ Clojure: Mükemmel modelleme; Lisp’e en yakın; JVM üzerinde harika bir runtime

→ Elixir: Deployment ve concurrency için mükemmel runtime; harika geliştirici deneyimi; nispeten küçük bir ekosistem

→ Erlang: Deployment ve concurrency için mükemmel runtime; geliştirici deneyimi biraz daha zorlayıcı; nispeten küçük bir ekosistem

→ Elm: Gelecek vaat ediyor; IBM iyi örnekler paylaşıyor; küçük bir ekosistem

→ Flow: JS için ilginç bir iyileştirme; ancak geliştiriciler uzaklaşıyor

→ Go: Harika geliştirici deneyimi; mükemmel concurrency; dili tuhaflaştıran bazı kötü kararlar alınmıştı

→ Haskell: En iyi fonksiyonel dil; küçük geliştirici topluluğu; production’da çok fazla başarı hikâyesi yok

→ Java: En iyi runtime; mükemmel ekosistem; ortalama bir geliştirici deneyimi

→ JavaScript: En popüler dil; en geniş ekosistem

→ Kotlin: Java’nın birçok yönünü iyileştiriyor; JetBrains’in güçlü desteği; Java’dan Kotlin’e geçişte çeşitli başarı örnekleri

→ Python: Sistem yönetimi tarafında en popüler dil; iyi analiz araçları; iyi web framework’leri; Google Go’yu seçince gözden düştü

→ Ruby: En iyi geliştirici deneyimi; en iyi web framework’leri; harika topluluk; aşırı yavaş; paketlemesi zor

→ Rust: En iyi yeni dil; Zero-cost abstractions (soyutlama yapılsa da hız düşmez) vurgusu; concurrency vurgusu; nispeten küçük ekosistem; bazı compiler optimizasyonlarında sınırlar var (örneğin belleğe doğrudan erişim için unsafe gerekmesi gibi)

→ TypeScript: JavaScript’e type ekler; mükemmel bir transpiler; geliştiriciler giderek JS’den TS’ye geçiyor; Microsoft’un güçlü desteği

• VM tabanlı seçenekler tercih edilmemeye karar verildi (çünkü karmaşıklığı artırıyor)

• En hızlı runtime için JS ve C seçilir

• En iyiye çok yakın hızda runtime için TypeScript ve Rust seçilir

• Eğer VM ve web framework seçilseydi

→ Closer ve Luminous

→ Java ve Spring

→ Elixir ve Phoenix