Yazılım Mimarisinde Teknik Tasarım Dokümanı (TDD) Nasıl Yazılır? (Rehber ve Şablon)
Yazılım Mimarisinde Teknik Tasarım Dokümanı (TDD) Nasıl Yazılır? (Rehber ve Şablon)
Yazılım dünyasında sıkça karşılaşılan bir senaryo vardır: Bir özellik veya yeni bir mikroservis geliştirilmeye karar verilir. Geliştiriciler hemen kodlamaya başlar. Birkaç hafta sonra, entegrasyon aşamasında aslında sistemin ölçeklenemeyeceği, güvenlik açıklarının olduğu veya mevcut veri tabanı yapısıyla uyuşmadığı fark edilir. Sonuç? Kaybedilen zaman, çöpe giden emek ve stresli bir kriz yönetimi.
İşte tam bu noktada Teknik Tasarım Dokümanı (Technical Design Document - TDD) devreye girer.
Not: Bu makalede bahsedeceğimiz TDD, "Test-Driven Development" (Test Güdümlü Geliştirme) değil, Technical Design Document (Teknik Tasarım Dokümanı) anlamına gelmektedir.
Bu rehberde, yazılım mimarisinin en önemli taşlarından biri olan TDD’nin ne olduğunu, hangi amaca hizmet ettiğini, içeriğinde nelerin yer alması gerektiğini ve başarılı bir dokümanın nasıl yazılacağını inceleyeceğiz. Yazının sonunda ise projelerinizde hemen kullanabileceğiniz pratik bir TDD şablonu bulacaksınız.
1. Teknik Tasarım Dokümanı (TDD) Nedir ve Hangi Amaca Hizmet Eder?
Teknik Tasarım Dokümanı (TDD), bir yazılım problemini çözmek için önerilen mimariyi, veri modellerini, sistem ilişkilerini ve teknik kararları detaylandıran yaşayan bir belgedir. Kod yazılmadan önce hazırlanır ve projenin "mavi kopyası" (blueprint) görevini görür.
TDD Yazmanın Temel Amaçları:
- Hizalama (Alignment) Sağlamak: Geliştiriciler, ürün yöneticileri (PM), sistem mimarları ve paydaşların aynı sayfada olmasını sağlar. Herkes neyin, neden ve nasıl yapılacağını önceden bilir.
- Riskleri Erken Aşamalarda Azaltmak: Kodlamaya başlamadan önce potansiyel darboğazları (bottlenecks), güvenlik açıklarını ve entegrasyon sorunlarını tespit etmeye yardımcı olur. Kağıt üzerinde hata yapmak, üretim ortamında (production) hata yapmaktan bin kat daha ucuzdur.
- Fikir Birliği ve Geri Bildirim Almak: Ekip üyelerinin tasarıma meydan okumasına (challenge etmesine) ve alternatif, daha iyi çözümler sunmasına olanak tanır.
- Geleceğe Yönelik Belgeleme (Documentation): Projeye yeni katılan bir geliştirici için sistemin neden o şekilde tasarlandığını anlatan harika bir başvuru kaynağıdır.
2. Bir TDD’nin İçeriğinde Neler Yer Almalıdır?
İyi bir TDD ne çok kısa ne de boğucu derecede uzun olmalıdır. Temel olarak şu bölümleri içermelidir:
A. Başlık ve Meta Bilgiler
Dokümanın kim tarafından, ne zaman yazıldığı ve şu anki durumunun ne olduğu (Taslak, İncelemede, Onaylandı) belirtilir.
B. Özet (Abstract / Executive Summary)
Sistemin veya özelliğin ne olduğunu ve neden yapıldığını açıklayan, teknik olmayan kişilerin de anlayabileceği 1-2 paragraflık kısa bir özet.
C. Bağlam ve Problem Tanımı (Context & Problem Statement)
Biz şu an hangi problemi çözmeye çalışıyoruz? Mevcut sistemdeki eksiklik veya iş ihtiyacı nedir? Bu bölüm, projenin varoluş sebebini açıklar.
D. Hedefler ve Hedef Dışı Durumlar (Goals & Non-Goals)
- Hedefler: Bu projenin başarıyla tamamlanmasıyla neyi elde edeceğiz? (Örn: "Ödeme işlemlerinin süresini 2 saniyenin altına indirmek.")
- Hedef Dışı Durumlar (Non-Goals): Kapsam kaymasını (scope creep) önlemek için bu projede neyi yapmayacağımızı netleştirmek kritik önem taşır.
E. Önerilen Mimari Tasarım (Proposed Architecture)
İşin en teknik kısmıdır. Sistem bileşenlerinin birbiriyle nasıl konuşacağını gösteren diyagramlar (C4 Model, Sequence Diagram vb.) ve veri akışları bu bölümde yer alır.
F. Veri Modeli ve Depolama (Data Model & Storage)
Hangi veri tabanları kullanılacak? Yeni tablolar veya şemalar nasıl olacak? Veri ilişkileri (ERD) nasıl kurulacak?
G. Güvenlik, Ölçeklenebilirlik ve Performans (Security, Scalability & Performance)
- Veriler nasıl şifrelenecek?
- Sistem yüksek yük altında nasıl davranacak? (Yatay ölçekleme, önbelleğe alma/caching stratejileri).
- KVKK/GDPR uyumluluğu nasıl sağlanacak?
H. Alternatif Çözümler ve Ödünleşimler (Alternatives Considered & Trade-offs)
Neden X teknolojisini değil de Y teknolojisini seçtik? Hangi alternatifleri değerlendirdik ve neden eledik? Bu bölüm, mimarın kararlarının arkasındaki mantığı gösterir.
I. Kilometre Taşları ve Planlama (Milestones & Plan)
Geliştirme aşamaları, tahmini süreler ve teslimat planı.
3. Başarılı Bir TDD Nasıl Yazılır? (İpuçları)
- Sade ve Net Bir Dil Kullanın: Süslü kelimelerden kaçının. Amacınız edebi bir eser yazmak değil, karmaşık bir sistemi en basit şekilde anlatmaktır.
- Görsellerden Yararlanın: "Bir resim bin kelimeye bedeldir." Sistem mimarisini anlatmak için Mermaid.js, Miro, Draw.io veya Lucidchart gibi araçlarla diyagramlar çizin.
- Geri Bildirime Açık Olun: Dokümanı yazdıktan sonra ekibinize "RFC" (Request for Comments) olarak gönderin ve yorum yapmalarını isteyin.
- Güncel Tutun: Proje sürecinde mimaride bir değişiklik yapıldıysa, bunu TDD'ye de yansıtın. Doküman yaşayan bir organizmadır.
4. Basit Bir TDD Şablonu (Markdown Formatında)
Aşağıdaki şablonu kopyalayarak kendi projelerinizde bir başlangıç noktası olarak kullanabilirsiniz.
# Teknik Tasarım Dokümanı (TDD): [Proje Adı]
* **Yazar(lar):** [Adınız Soyadınız]
* **Durum:** [Taslak / İncelemede / Onaylandı]
* **Tarih:** [GG.AA.YYYY]
* **İlgili Kişiler:** [Ürün Yöneticisi, Mimarlar, Geliştiriciler]
---
## 1. Özet (Summary)
[Projenin/özelliğin ne olduğunu ve neyi amaçladığını açıklayan 1-2 paragraflık kısa özet.]
## 2. Bağlam ve Problem Tanımı (Context)
[Bu projeye neden ihtiyaç duyuldu? Mevcut sistemdeki acı noktaları (pain points) nelerdir?]
## 3. Hedefler ve Hedef Dışı Durumlar (Goals & Non-Goals)
### Hedefler
* [Hedef 1: Örn: Yeni üyelik sisteminin mikroservis mimarisine taşınması]
* [Hedef 2: Örn: Yanıt sürelerinin < 100ms olması]
### Hedef Dışı Durumlar (Non-Goals)
* [Hedef Dışı 1: Örn: Bu aşamada mobil uygulamanın arayüzü yenilenmeyecektir.]
## 4. Önerilen Mimari Tasarım (Proposed Design)
### 4.1. Sistem Mimarisi Diyagramı
```mermaid
graph TD
A[İstemci / Client] -->|HTTPS| B[API Gateway]
B --> C[Kullanıcı Servisi]
B --> D[Ödeme Servisi]
C --> E[(PostgreSQL)]
D --> F[(Redis)]
4.2. Bileşen Açıklamaları
- Bileşen A (API Gateway): İstekleri karşılar ve ilgili servislere yönlendirir.
- Bileşen B (Kullanıcı Servisi): Kullanıcı kayıt ve giriş işlemlerini yönetir.
5. Veri Tasarımı (Data Design)
Yeni Veri Şeması (Örnek)
CREATE TABLE users (
id UUID PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
6. Güvenlik ve Uyumluluk (Security & Compliance)
- Kimlik doğrulama için JWT kullanılacaktır.
- Hassas kullanıcı verileri (şifreler) Argon2id algoritması ile hash'lenecektir.
7. Değerlendirilen Alternatifler ve Ödünleşimler (Trade-offs)
- Alternatif A (MongoDB): Esnek şema sunduğu için değerlendirildi ancak ilişkisel veri bütünlüğü (ACID) gereksinimleri nedeniyle PostgreSQL tercih edildi.
8. Kilometre Taşları ve Tahmini Takvim (Milestones)
- Milestone 1: Veri tabanı tasarımı ve servis iskeletinin kurulması (1. Hafta)
- Milestone 2: API uç noktalarının geliştirilmesi ve entegrasyonu (2. Hafta)
- Milestone 3: Testler ve Canlıya Geçiş (3. Hafta) ```
Sonuç
Teknik Tasarım Dokümanı (TDD) yazmak, başlangıçta ekstra bir iş yükü gibi görünse de uzun vadede projelerin başarısını katlar, teknik borçları (technical debt) azaltır ve ekibin verimli çalışmasını sağlar.
Unutmayın; "Kod yazmak kolaydır, doğru şeyi doğru şekilde inşa etmek ise mimari disiplin gerektirir."
Siz de bir sonraki projenizde yukarıdaki şablonu kullanarak ilk TDD'nizi yazabilir ve ekibinizdeki değişimi gözlemleyebilirsiniz!