Merhaba yazılımperver dostlarım, yeni maceramıza yönelik ilk yazım, ekiplerinizle ve projelerinizde kullanabileceğiniz ve faydasını göreceğiniz Mimari Karar Kaydı (Architecture Decision Record) konusu üzerine olacak. Açıkçası, ben de uzun süredir bu kayıtları Atlassian Confluence aracı vasıtasıyla kullanıyorum ve faydasını gördüm.
İçerik
Mimari Karar Kaydı (MKK) Nedir?
İsminden de anlaşılacağı üzere MKK, alınan bir mimari karara yönelik kaydı/dokümanı temsil eder.
Peki bu neden önemli sorusuna bakacak olursak:
- Öncelikli olarak, bu tarz kararların dokümante edilmesi ve unutulup gitmesinin önüne geçilmesi, bilgi paylaşımı,
- Kararın alınmasının arkasında yatan sebepler, değerlendirilen seçenekler, riskler ve olasın sonuçlarının anlaşılması ve kayıt altına alınması,
- Alınan kararlar konusunda fikir birliği ve ortak dilin oluşturulması,
- Bir önceki kalem ile de ilintili olarak, iletişim ve şeffaflığın arttırılması,
- Bilgi kaybının önüne geçilerek, yeni başlayan kişiler için yardımcı olma.
Bir diğer açıdan bu MKK’lar aslında sistem için neden yaptık sorularının yanıtlarını içerir.
Bu kavramı ilk ortaya atanlardan birisi de Michael Nygard’dır ve buna yönelik yazısına Documenting Architecture Decisions‘dan erişebilirsiniz.
Bir MKK Nasıl Olmalıdır?
Yazılacak olan MKK’ların amacına hizmet edebilmesi için:
- Öncelikli olarak her MKK’nın yapısı ortak ve tutarlı olmalıdır,
- Mümkün olduğunca basit ve kısa tutulmalıdır,
- Tek bir karar odaklanmalıdır,
- Kararlar net ve açık bir şekilde ifade edilmelidir,
- En azından aşağıdaki başlıkları içermelidir:
- Bağlam, Karar alınacak konu/problem
- Değerlendirilen opsiyonlar
- Verilen karar
- Avantaj/dezavantajlar
- Neden önemli olduğu ve bağlamı,
- Zaman
- Durum
- Öneri, Kabul Edildi, Reddedildi, XXX tarafından geçersiz kılındı
- Kararlar geçersiz olabilir, bu durumda güncel kararlar bunu ifade etmelidir,
- Herkesin erişebileceği bir yerde bulunmalıdır,
- İlgili karar için gerekli koşullar oluştu mu?
gibi konulara dikkat edilmelidir.
Peki MKK’ları nerede ve nasıl tutabiliriz.
Git repolarınız altında tutabilirsiniz:
|
1 2 3 4 5 6 7 8 |
my_project/ ├── src/ ├── include/ ├── CMakeLists.txt ├── adr/ │ ├── adr_001_logger_kutuphanesi.md │ ├── adr_002_json_kutuphanesi.md │ └── README.md <-- (MKK listesi) |
Bu sayede hem sürüm kontrolü yapabilir, hem herkes ulaşabilir hem de proje ile birlikte takip edilir. Karar için de PR mekanizması kullanılabilir.
İsimlendirme yaparken de artan ve eşsiz numara vermekte fayda var. Bir MKK geçersiz kılınsa da numarası tekrar kullanılmamalıdır.
Bence çok elzem değil ama kararlara göre de (geçerli/geçersiz) ayrı dizinlere konulabilir.
İçeriğini de markdown formatında yazmanızda fayda var.
Örnek bir MKK
Bu başlık altında C++ uygulaması için kullanılacak loglama kütüphanesine yönelik bir karar metnini bulabilirsiniz.
Aşağıdaki örnek ve şablon MKK’lar için https://github.com/yazilimperver/architecture-design-records/tree/main sayfasına başvurabilirsiniz.
ADR-001: Loglama kütüphanesine karar verilmesi
- Durum: Kabul Edildi
- Tarih: 2025-05-19
Bağlam
Projede kapsamlı bir loglama altyapısına ihtiyaç duyulmaktadır. Bu loglar:
- Geliştirme sırasında hata ayıklamayı kolaylaştırmalı,
- Gömülü sistemlerde düşük gecikme ve hafiflik sunmalı,
- Gerçek zamanlı senaryolarda bloklamaya yol açmamalı,
- Kolay yapılandırılabilir ve gerektiğinde dosya/log sunucusuna yönlendirilebilir olmalıdır.
Ek olarak, mevcut sistemde CMake kullanılmakta ve harici bağımlılıkların kolayca entegre edilmesi önem arz etmektedir.
Karar
Logger kütüphanesi olarak spdlog kullanılması kararlaştırılmıştır.
Gerekçeler
- Performans:
spdlog, sıfır dinamik bellek kullanımı ve asenkron loglama gibi özelliklerle yüksek performans sunar. - Bağımsızlık: STL harici bir bağımlılığı yoktur, sistemle kolay entegre olur.
- Kolay kullanım:
fmtile uyumlu API sayesinde kullanıcı dostudur. - Dosya/Döngüsel Loglama: Günlük döndürme (rotating log) ve günlük büyüklüğüne göre sınırlandırma gibi özellikler yerleşiktir.
- Topluluk ve destek: Yaygın kullanıma sahiptir, aktif geliştirme devam etmektedir.
- CMake ile kolay entegrasyon:
FetchContentveadd_subdirectoryile hızlı entegre edilir.
Alternatifler
-
Boost.Log
- Artılar: Gelişmiş özellikler ve Boost ekosistemine tam uyumluluk.
- Eksiler: Kurulum ve yapılandırma karmaşık, bağımlılık boyutu yüksek.
-
log4cpp
- Artılar: Olgun bir proje.
- Eksiler: Bakımı yavaşlamış, modern C++ standartlarını yeterince desteklemiyor.
-
DIY (kendi logger sistemimizi yazmak)
- Artılar: Tam kontrol sağlar.
- Eksiler: Zaman kaybı, test yükü ve hataya açıklık yaratır.
Sonuçlar
- Projeye
spdlogkütüphanesiFetchContentüzerinden entegre edilecek. - Varsayılan olarak hem konsola hem dosyaya loglama yapan bir yapı kurulacak.
- Gömülü hedeflerde dosya loglama devre dışı bırakılabilir olacak.
- Geliştirici rehberine
spdlogkullanım örnekleri ve stil kuralları eklenecek.
Evet sevgili dostlar, yazılım geliştirme kariyerinizde muhakkak ihtiyacınız olacağını düşündüğüm Mimari Karar Kayıtlarına yönelik yazımın sonuna geldik. Bir sonraki yazımda görüşmek dileğiyle, kendinize çok iyi bakın.