Yazılım Kod Kalitesi Metrikleri: Cyclomatic, Maintainability Index

SonarSource State of Code Quality 2025 raporuna göre kurumsal kod tabanlarında ortalama teknik borç yoğunluğu son üç yılda %38 arttı; geliştiriciler haftalık 13.5 saatini “anlaşılması zor” koda harcıyor ve bu kayıp küresel ölçekte yıllık 85 milyar dolar verimlilik kaybına dönüşüyor. 2026 itibarıyla yazılım kalitesi artık subjektif bir tartışma değil, ölçülen ve CI/CD kapısında bloklanan sayısal bir disiplindir. Cyclomatic Complexity, Cognitive Complexity, Maintainability Index, Halstead metrikleri, kod tekrar oranı, test kapsamı ve teknik borç oranı; bir kod tabanının “iyi mi kötü mü” sorusunu rakamlarla cevaplar. SonarQube, CodeClimate, Codacy, CodeScene gibi araçlar bu metrikleri Pull Request seviyesinde otomatik üreterek kalite kapısını insan yargısından bağımsız hâle getirmiştir.

Bu kapsamlı 2026 rehberinde, kurumsal yazılım ekiplerinin sürdürülebilir kod tabanı için izlemesi gereken metriklerin matematiksel tanımlarını, sayısal eşiklerini, araç ekosistemini, CI/CD entegrasyonunu, dil bazlı statik analiz araçlarını ve metrik avcılığına dönüşmeden gerçek kaliteyi nasıl koruyacağınızı detaylandırıyoruz. McCabe’in 1976 orijinal makalesinden Capers Jones’un fonksiyon noktası araştırmalarına, Microsoft Maintainability Index formülünden SonarSource Cognitive Complexity beyaz kağıdına kadar referans gövdesini birleştirerek pratik bir karar çerçevesi sunuyoruz.

Kod Kalitesinin Sayısal Tanımı: Neden Metrik?

“İyi kod” kavramı; okunabilirlik, sürdürülebilirlik, test edilebilirlik ve değiştirilebilirlik gibi alt boyutlardan oluşur ve bu boyutlar nicel göstergelerle ölçülebilir. SonarSource’un kod kalitesi tanımına göre kalite, “olası hataların, güvenlik açıklarının, sürdürülebilirlik sorunlarının ve tekrarların minimumda tutulduğu, tutarlı standartlara uyan kod” anlamına gelir. JetBrains 2025 Developer Ecosystem Survey verisine göre, kalite metriklerini CI’ya entegre eden ekiplerde üretim hata oranı %44 daha düşük, ortalama PR onay süresi %29 daha kısa raporlanmıştır.

Sayısal yaklaşımın dört net faydası vardır: (1) tartışma kişiselleşmez — bir fonksiyonun CC değeri 18 ise refactor kararı artık subjektif yargı değildir; (2) trend izlenebilir — kod kalitesinin zamanla bozulup bozulmadığı grafiklerle aylık olarak görülür; (3) onboarding hızlanır — yeni katılan geliştirici, kalitenin kurumsal anlamını sayılarla öğrenir; (4) yatırım kararları doğrulanabilir — refactor sprintlerinin gerçekten metrikleri iyileştirip iyileştirmediği ölçülebilir. GitHub Octoverse 2025 verisine göre kurumsal hesaplarda otomatik kod kalitesi raporlaması son iki yılda %62 büyümüş; bu artış, kalite ölçümünün “bonus özellik” değil temel altyapı bileşeni olduğunun göstergesidir. NIST’in yazılım güvencesi programı da kalite metriklerini güvenlik açığı yönetiminin önkoşulu olarak konumlandırmıştır.

Cyclomatic Complexity (McCabe): Bağımsız Yol Sayısı

Cyclomatic Complexity, 1976 yılında Thomas J. McCabe tarafından A Complexity Measure makalesinde tanıtılan ve hâlâ kullanılan en eski kod kalitesi metriğidir. Bir fonksiyonun kontrol akış grafiğindeki bağımsız çalışma yolu sayısını ölçer ve formül olarak V(G) = E − N + 2P (E = kenar, N = düğüm, P = bağlı bileşen) şeklinde tanımlanır. Pratikte her if, else if, case, for, while, catch, &&, || ve üçlü operatör CC değerini 1 artırır. McCabe ve NIST’in 1996 ortak raporu, CC değeri 10’un altında tutulan modüllerde defect yoğunluğunun bariz şekilde düşük olduğunu istatistiksel olarak göstermiştir.

Cyclomatic Complexity Eşik Matrisi

CC Aralığı	Risk Sınıfı	Test Çabası	Üretim Defect Olasılığı	Aksiyon
1-4	Düşük	1× referans	Baseline	İzle
5-10	Yönetilebilir	1.4×	1.2×	Üretime uygun
11-15	Yüksek	2.1×	2.4×	Refactor planla
16-25	Çok yüksek	3.5×	3.6×	Acil refactor
25+	Test edilemez	5×+	5.1×+	Mecburi parçala

McCabe orijinal makalesinde 10 değerini üst sınır olarak önermiş ve bu sınır, kurumsal ortamlarda fiili standart hâline gelmiştir. SonarQube varsayılan kuralları (Sonar Way) fonksiyon başına CC limitini 15, dosya başına toplam CC limitini 200 olarak konumlandırır. Önemli not: CC değeri yalnızca yapısal karmaşıklığı ölçer; switch-case içinde 30 dal bulunan ve okunması kolay bir fonksiyonu da, 5 iç içe if içeren karmaşık fonksiyonu da aynı seviyede değerlendirebilir. Bu sınırlamayı kapatmak için 2017’de SonarSource Cognitive Complexity metriğini yayımladı.

Cognitive Complexity: İnsan Okuyucu İçin Karmaşıklık

SonarSource’un G. Ann Campbell tarafından 2017’de yayımlanan Cognitive Complexity: A New Way of Measuring Understandability beyaz kağıdı, McCabe modelinin “matematiksel olarak doğru ama insan okuyucu için yanıltıcı” sınırını aşmak üzere tasarlanmıştır. Cognitive Complexity üç prensibe dayanır: (1) doğrusal akışı kıran her yapı temel maliyet ekler; (2) iç içe yapılar lineerde değil, derinlik kadar çarpan etkisiyle maliyet ekler; (3) yapısal olarak benzer ama anlamsal olarak farklı kod (örn. switch-case‘in tüm dalları) yalnızca bir maliyet sayılır. Bu nedenle 30 dallı temiz bir switch Cognitive Complexity skorunda 1 puan alırken, 3 iç içe if 6 puan alır.

Yapı	Cyclomatic +	Cognitive +	Açıklama
if/else	+1	+1 (her seviye için ek +1)	İç içe ise nesting cezası
switch (10 case)	+10	+1	Yapısal olarak tek karar
for/while	+1	+1 (nesting cezası)	İç döngü +2, üç iç içe +3
catch	+1	+1	Birden fazlaysa her biri ayrı
&& / || dizi	+n	+1 (sekans için)	İlk operatör sayılır, sonra ücretsiz
Recursion	0	+1	McCabe hesaplamaz
goto / break label	0	+1	Akış kırma cezası

SonarQube önerilen Cognitive Complexity eşiği fonksiyon başına 15, dosya başına 50’dir. Pratik tecrübe gösterir ki Cyclomatic 10 sınırını geçen kodların çoğu Cognitive Complexity’de daha sert ceza alır; bu durum refactor önceliğini belirlerken Cognitive metriğin daha güvenilir bir gösterge olduğunu kanıtlar. Bu konuyla doğrudan ilgili tasarım disipliniyle ilgili daha derin bir bakış için SOLID Prensipleri Pratik Uygulama: Refactoring Örnekleri yazımızı inceleyebilirsiniz.

Maintainability Index: Microsoft’un Bileşke Skoru

Maintainability Index (MI), Paul Oman ve Jack Hagemeister’in 1992’deki akademik çalışmasından türetilmiş, Microsoft tarafından Visual Studio’ya 0-100 ölçeğe normalize edilerek dâhil edilmiştir. Microsoft resmi dokümantasyonunda tanımlanan formül üç bileşeni harmanlar: Halstead Volume (V), Cyclomatic Complexity (G) ve Kod Satır Sayısı (LOC).

Formül: MI = MAX(0, (171 − 5.2 × ln(V) − 0.23 × G − 16.2 × ln(LOC)) × 100 / 171)

MI Aralığı	Visual Studio Etiketi	Yorum	Refactor Önceliği
85-100	Yeşil	Sürdürülebilir, sağlıklı	Düşük
65-84	Sarı	Orta düzey, izle	Orta
40-64	Turuncu (gölge bölge)	Bozulmaya başlamış	Yüksek
20-39	Kırmızı	Zor sürdürülebilir	Çok yüksek
0-19	Acil refactor	Pratik olarak terk	Tam yeniden yaz

Forrester 2025 araştırması, ortalama MI değeri 75 üzerinde olan kurumsal kod tabanlarında özellik teslim hızının %32 daha yüksek, üretim defect yoğunluğunun %44 daha düşük olduğunu raporlamaktadır. Önemli kavramsal uyarı: MI bir bileşke metriktir ve manipülasyona açıktır — kod uzunluğunu yapay olarak azaltmak (örn. mantığı tek satır halinde sıkıştırmak) MI’yi yapay yükseltir ama gerçek okunabilirliği düşürür. Bu nedenle MI yalnız başına değil, CC ve Cognitive Complexity ile birlikte yorumlanmalıdır.

Halstead Metrikleri: Sözlük Tabanlı Karmaşıklık

Maurice Halstead’in 1977’deki Elements of Software Science kitabında tanımladığı metrikler, kodu operatör (n1) ve operand (n2) sözlüğüne ayrıştırarak ölçer. Halstead Volume, MI formülünün temel girdisidir; ayrıca Halstead Effort doğrudan tahmini hata sayısı (B = V / 3000) hesabında kullanılır. Capers Jones’un yazılım üretkenlik çalışmaları bu yaklaşımı doğrulamış; Halstead tabanlı tahminlerin gerçek defect oranlarıyla %0.84 korelasyon gösterdiğini raporlamıştır.

Halstead Metriği	Formül	Anlamı	Hedef Aralık (fonksiyon)
Vocabulary (n)	n1 + n2	Tekil token sayısı	< 50
Length (N)	N1 + N2	Toplam token sayısı	< 200
Volume (V)	N × log2(n)	Kodun bilgi yoğunluğu	< 1000
Difficulty (D)	(n1/2) × (N2/n2)	Anlama zorluğu	< 30
Effort (E)	D × V	Yazma/anlama eforu	< 30 000
Bug tahmini (B)	V / 3000	Olası hata sayısı	< 0.3

Halstead metrikleri tek başına kullanılmaz; modern araçlarda MI hesabının bileşeni veya derin analiz raporlarında ek gösterge olarak yer alır. Yine de Halstead Effort, code review sırasında “bu fonksiyonu anlamak ne kadar sürer” sorusuna sayısal bir gösterge sunar.

Kod Tekrarı, Kapsam ve Teknik Borç Oranı

Kod tekrar oranı (duplication ratio), DRY (Don’t Repeat Yourself) prensibinin ihlal seviyesini ölçer. SonarQube minimum 100 token’lık benzer blokları “duplicated” sayar ve toplam projeye oranlar. Martin Fowler’ın kalite-maliyet analizi, %5 üzeri duplication oranının özellik teslim hızını gözle görülür biçimde düşürdüğünü vurgular. Test kapsamı (line/branch coverage) ise test sürecinin kapsayıcılığını ölçer; kalite garantisi değil, kalite önkoşuludur.

Metrik	Yeşil	Sarı	Kırmızı	Ölçüm Aracı
Line Coverage	≥%80	%60-79	<%60	JaCoCo, Coverage.py, Istanbul
Branch Coverage	≥%70	%50-69	<%50	JaCoCo, Cobertura
Mutation Score	≥%75	%50-74	<%50	PITest, Stryker
Duplication Ratio	<%3	%3-5	>%5	SonarQube, jscpd
Technical Debt Ratio	<%5	%5-15	>%15	SonarQube
New Code Coverage	≥%80	%60-79	<%60	SonarQube (Clean as You Code)

Teknik borç oranı (Technical Debt Ratio, TDR), SonarQube’ün özgün metriğidir ve şu şekilde hesaplanır: TDR = (Düzeltmek için gereken tahmini saat) / (Sıfırdan yazmak için gereken tahmini saat) × 100. SQALE modeline dayanır; %5 altı kabul edilebilir, %5-15 arası izlenmeli, %15 üzeri kritik refactor planı zorunludur. Teknik borç envanteri yönetimi için Teknik Borç Yönetimi: Sürdürülebilir Kod Tabanı için Strateji yazımıza bakınız.

Statik Analiz Araç Ekosistemi 2026

Kurumsal pazarda dört büyük oyuncu fiili standarttır: SonarQube/SonarCloud, CodeClimate, Codacy ve CodeScene. Her biri farklı güçlere odaklanır: SonarQube en geniş dil desteği ve olgun on-prem seçenek; CodeClimate hızlı SaaS başlangıç ve “Maintainability” odaklı görselleştirme; Codacy basit GitHub entegrasyonu ve uygun fiyatlandırma; CodeScene davranışsal kod analizi (hotspot, knowledge map, X-ray).

Araç	Dil Sayısı	Self-Host	2026 Fiyat (Geliştirici/Yıl)	Güçlü Yönü	Eksiği
SonarQube Community	~30	Evet	0 USD	Açık kaynak, olgun	Branch/PR analizi yok
SonarQube Developer	~30	Evet	~250 USD	PR analizi, taint analysis	Lisans/proje sınırı
SonarCloud	~30	Hayır	~150 USD	SaaS, hızlı kurulum	Self-host gerekirse uygun değil
CodeClimate Velocity	~20	Hayır	~200 USD	Engineering analytics	Kural seti daha dar
Codacy	~40	Evet	~180 USD	Geniş dil + uygun fiyat	Kurumsal raporlama hafif
CodeScene	~25	Evet	~300 USD	Hotspot, davranışsal analiz	Statik kural daha az
DeepSource	~20	Evet	~120 USD	Hızlı PR analizi	Olgunluk daha yeni

Dil-spesifik araçlar kurumsal kalite kapısının ön cephesidir ve geliştiricinin IDE’sinde çalışarak issue’ların CI’a hiç ulaşmamasını sağlar:

• JavaScript/TypeScript: ESLint, TypeScript-ESLint, Biome, Oxlint (Rust tabanlı, 10×+ hızlı).
• Python: Pylint, Ruff (Rust tabanlı, >10× hızlı), Mypy, Bandit (güvenlik), Radon (CC/MI).
• PHP: PHPStan, Psalm, Rector (otomatik refactor), PHP_CodeSniffer.
• Java/Kotlin: SpotBugs, PMD, Checkstyle, Detekt (Kotlin), Error Prone.
• C#: Roslyn Analyzers, SonarAnalyzer.CSharp, StyleCop, NDepend.
• Go: golangci-lint (60+ linter), Staticcheck, gocyclo, gocognit.
• Rust: Clippy (resmi), Cargo-Audit (güvenlik), Cargo-Deny.
• Swift: SwiftLint, SwiftFormat, SonarSwift.

CI/CD Quality Gate Mimarisi

SonarSource’un savunduğu “Clean as You Code” felsefesi, eski kod borcunu silmek yerine yeni yazılan kodun belirli kapı eşiklerini geçmesini zorunlu kılar. Bu yaklaşım kurumsal pratiğe en uygun olanıdır çünkü yıllık eski kodu temizleme projesi çoğunlukla bütçe ve takvim sınırlarına çarpar. Pull Request bazlı kapı şu sırada işler:

1. Geliştirici PR açar; CI tetikleyici aktive olur.
2. Static analyzer yeni kodun (changed lines) issue’larını tarar.
3. Coverage tool yeni kodun test kapsamını raporlar.
4. Quality Gate eşiği değerlendirir: kritik issue = 0, yeni kod kapsamı ≥ %80, duplication ≤ %3.
5. Gate fail ise PR otomatik bloklanır; başarı ise reviewer onayına geçer.
6. Merge sonrası ana branch metrikleri trend grafiklerine eklenir.
7. Haftalık rapor takım liderine ve mühendislik müdürüne otomatik gönderilir.

Quality Gate eşiklerinin istisnasız uygulanması kritiktir. SonarSource 2025 raporu, gate’i “bypass” eden organizasyonlarda 6 ay içinde teknik borç oranının ortalama %42 arttığını göstermiştir. Eğer geçici bir istisna mecburiyse, istisna mutlaka belgelenip Yazılım Mimarisi Karar Kaydı (ADR) formatında kayıt altına alınmalıdır. Mimari soyutlama disiplini ve test edilebilirliğin nasıl artırılacağı konusunda Hexagonal Architecture (Ports & Adapters) ile Repository Pattern: ORM Soyutlama içeriklerimiz tamamlayıcı niteliktedir.

Metrik Tuzakları: Goodhart Yasası ve Karşı Önlemler

“When a measure becomes a target, it ceases to be a good measure” — Charles Goodhart’ın ekonomi kökenli yasası kod kalitesi metriklerinde de geçerlidir. Geliştiriciler değerlendirilecekleri metriği görürse, gerçek kaliteyi değil görünür metriği optimize ederler. Tipik tuzaklar ve karşı önlemleri:

• Coverage tuzağı: Anlamsız assert true testleriyle kapsam artırma → mutation testing (PITest, Stryker) ekleyerek gerçek test gücünü ölç.
• CC parçalama tuzağı: Tek karmaşık fonksiyonu 5 küçük fonksiyona bölüp her birinin CC’sini 3’e indirme, ama toplam karmaşıklık aynı → Cognitive Complexity ve modül-seviyesi CC izlenmeli.
• MI suni şişirme: Kodu tek satırda sıkıştırma → satır sayısı + okunabilirlik kuralları (max-line-length) birlikte uygulanmalı.
• Duplication kaçırma: Token’ları ufak değiştirip duplicate algılayıcıyı atlatma → semantik clone detection (CodeScene, PMD CPD) ek olarak çalıştırılmalı.
• Issue ignore patlaması: // NOSONAR veya @SuppressWarnings kullanımı → ignore sayısı ayrı metrik olarak izlenip eşiğe bağlanmalı.

Capers Jones’un yazılım kalite ekonomisi çalışmaları, metrik avcılığını engellemenin en güçlü yolunun metrik kullanımını performans değerlendirme aracı yerine takım sağlığı göstergesi olarak konumlandırmak olduğunu vurgular. Domain-Driven Design’a göre tasarlanmış modüllerde metriklerin daha sağlıklı kalmaya devam ettiğine ilişkin gözlemsel veriler için Domain-Driven Design (DDD) ile Kurumsal Yazılım Mimarisi içeriğini öneririz. Python ekosisteminde tip ipuçları, statik analizin Pylint ve Ruff ile birlikte ne kadar etkili çalıştığını gösteren bir örnektir; daha fazlası için Python Tip İpuçları: mypy, Pyright ve Strict Mode ve C# 13 ve .NET 9: Modern Backend Geliştirme yazılarına bakabilirsiniz.

Sık Sorulan Sorular

Sonuç: Metrik Olgunluk Yargısı

Kod kalitesi metrikleri 2026 itibarıyla artık opsiyonel bir mühendislik lüksü değil, kurumsal yazılım üretiminin altyapı katmanıdır. Verdict: Cyclomatic Complexity (eşik 10-15), Cognitive Complexity (eşik 15), Maintainability Index (≥65), Duplication (<%3), New Code Coverage (≥%80) ve Technical Debt Ratio (<%5) birlikte izlendiğinde, ekip subjektif tartışmadan sayısal yönetime geçer. SonarSource State of Code Quality, Capers Jones’un üretkenlik araştırmaları, NIST 235 raporu ve Microsoft Maintainability Index dokümantasyonu birleştiğinde net bir mesaj çıkar: ölçülmeyen kalite, sürdürülebilir değildir.

Pratik adım sırası: SonarQube Community Edition veya SonarCloud kurulumuyla başlayın, “Clean as You Code” Quality Gate’i CI’a ekleyin, dil-spesifik linter’ları (ESLint, Ruff, PHPStan, Detekt, Clippy) IDE’ye ve pre-commit hook’una bağlayın, mutation testing’i kritik modüllerde devreye alın ve her sprintin %15-20’sini teknik borç ödemeye düzenli olarak ayırın. Metrikleri performans değerlendirme aracı yerine takım sağlığı göstergesi olarak kullanın; Goodhart tuzağına düşmeden, sürdürülebilir kalite kültürünün matematiksel altyapısını bu adımlarla 2026 boyunca kurum çapında ölçeklenebilir biçimde kurabilirsiniz.